Documentation: Created "Installing BuildStream" Section

Included pedro's docker documentation at the end of this, as
an alternative for those who cannot obtain the base system
requirements to use BuildStream.

3 files changed, 230 insertions, 84 deletions

diff --git a/doc/source/docker.rst b/doc/source/docker.rst
deleted file mode 100644
index dbd8c9b0c..000000000
--- a/doc/source/docker.rst
+++ /dev/null
@@ -1,76 +0,0 @@
-.. _docker:
-
-Using BuildStream inside Docker
-===============================
-Some of the dependencies needed to use BuildStream are still not available in
-some Linux distributions.
-
-It is also possible that the users don't want to install these dependencies in
-their systems. For these cases, it's possible to use Docker.
-
-Here in this page we are going to explain how to use Docker for developing and
-running BuildStream.
-
-
-Building a Docker container to use BuildStream
-----------------------------------------------
-To create a Docker image ready to use with BuildStream you need to run the
-following command in the top level directory of BuildStream repository.
-
-::
-
-    docker build -t buildstream .
-
-Options explained:
-
--  ``-t buildstream``: Tag the created container as ``buildstream``
-
-The container created will have BuildStream installed. If you want to run a
-different version, you have to switch to the modified source tree and build the
-container image running the same command, or with a different tag.
-
-
-Running BuildStream tests in Docker
------------------------------------
-To run the tests inside a Docker container, we only need to mount the
-repository inside the running container and run the tests. To do this run the
-following command:
-
-::
-
-    docker run -it -u $UID:$EUID -v `pwd`:/bst-src:rw --privileged -w /bst-src buildstream python3 setup.py test
-
-Options explained:
-
--  ``-it``: Interactive shell and TTY support.
--  ``-u $UID:$EUID``: Use $UID as user-id and $EUID as group-id when
-   running the container.
--  ``-v $(pwd):/bst-src:rw``: Mount BuildStream source tree in
-   ``/bst-src`` with RW permissions.
--  ``--privileged``: To give extra privileges to the container (Needed
-   to run some of the sandbox tests).
--  ``-w /bst-src``: Switch to the ``/bst-src`` directory when running the
-   container.
-
-
-Using BuildStream in a Docker container
----------------------------------------
-To use BuildStream build tool you will need to mount inside the container your
-workspace, and a folder that BuildStream will use for temporary data. This way
-we make the temporary data persistent between runs.
-
-Run the following command to run a bash session inside the container:
-
-::
-
-    docker run -it -u $UID:$EUID -v /path/to/buildstream/workspace:/src:rw -v /path/to/buildstream/tmp:/buildstream:rw buildstream bash
-
-Options:
-
--  ``-it``: Interactive shell and TTY support.
--  ``-u $UID:$EUID``: Use $UID as user-id and $EUID as group-id when
-   running the container.
--  ``-v /path/to/buildstream/workspace:/src:rw``: Mount your workspace in
-   ``/src`` inside the container.
--  ``-v /path/to/buildstream/tmp:/buildstream:rw``: Mount a temporary folder
-   where BuildStream stores artifacts, sources, etc.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 178dc06be..fe6bf693c 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -14,21 +14,23 @@ About BuildStream
 BuildStream is a flexible and extensible framework for the modelling of build
 pipelines in a declarative YAML format, written in python.
 
-BuildStream defines a pipeline as abstract elements related by their dependencies,
-and stacks to conveniently group dependencies together. 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
+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.
 
 
 Using BuildStream
 =================
-Here are some resources to help you get off the ground when creating your very
-first BuildStream project.
+Here are some resources to help understand the BuildStream format and also to get
+off the ground installing it on a new host.
 
+* :ref:`installing`
 * :ref:`format`
-* :ref:`docker`
 
 
 Elements
diff --git a/doc/source/install.rst b/doc/source/install.rst
new file mode 100644
index 000000000..0d7ac80d4
--- /dev/null
+++ b/doc/source/install.rst
@@ -0,0 +1,220 @@
+.. _installing:
+
+
+Installing BuildStream
+======================
+Until BuildStream is available in your distro, there are a few hoops to jump
+through to get started.
+
+If your system cannot provide the base system requirements for BuildStream,
+then we have some instructions below which can get you started using BuildStream
+within a Docker container.
+
+
+Installing base system requirements
+-----------------------------------
+BuildStream requires the following base system requirements:
+
+* python3 >= 3.4
+* PyGObject introspection bindings
+* OSTree >= v2016.8
+* OStree introspection data
+
+For the purpose of installing BuildStream while there are no distro packages,
+you will additionally need:
+
+* pip for python3 (only required for setup)
+* Python 3 development libraries and headers
+* git (to checkout buildstream)
+
+
+Here are some examples of how to prepare the base requirements on
+some distros.
+
+
+Debian Jessie
+~~~~~~~~~~~~~
+With jessie, you first need to ensure that you have the backports repository
+setup as described `here <https://backports.debian.org/Instructions/>`_
+
+By adding the following line to your sources.list::
+
+  deb http://ftp.debian.org/debian jessie-backports main
+
+And then running::
+
+  sudo apt-get update
+
+At this point you should be able to get the system requirements with::
+
+  sudo apt-get install \
+      python3 python3-dev python3-pip git \
+      python3-gi gir1.2-ostree-1.0 ostree \
+      bubblewrap
+
+
+Debian Stretch or Sid
+~~~~~~~~~~~~~~~~~~~~~
+For debian unstable or testing, only the following line should be enough
+to get the base system requirements installed::
+
+  sudo apt-get install \
+      python3 python3-dev python3-pip git \
+      python3-gi gir1.2-ostree-1.0 ostree \
+      bubblewrap
+
+
+User installation with pip
+--------------------------
+Once you have the base system dependencies, you can clone the buildstream
+git repository and install it as a regular user::
+
+  git clone git@gitlab.com:BuildStream/buildstream.git
+  cd buildstream
+  pip3 install --user .
+
+This will install buildstream and it's pure python dependencies directly into
+your user's homedir in ``~/.local``
+
+
+Upgrading with pip
+~~~~~~~~~~~~~~~~~~
+To upgrade a previously install BuildStream, you will need to pull the latest
+changes and reinstall as such::
+
+  pip3 uninstall buildstream
+  cd buildstream
+  git pull --rebase
+  pip3 install --user .
+
+
+Using virtualenv
+----------------
+If you want to install BuildStream in such a way that ``pip`` does not add
+any files to your home directory, you can use virtualenv. This is a bit less
+convenient because it requires you enter a special environment every time you
+want to use BuildStream.
+
+To use virtualenv, you will first need to install virtualenv with your
+package manager, in addition to the base requirements listed above.
+
+E.g. with debian systems::
+
+  sudo apt-get install python3-virtualenv
+
+At this point the following instructions will get you a virtual python
+environment that is completely encapsulated and does not interfere with
+your system or home directory::
+
+  # Clone the repository
+  git clone git@gitlab.com:BuildStream/buildstream.git
+  cd buildstream
+
+  # Create a virtualenv sandbox for the installation, you need to
+  # enable the system site packages in order to have access to the
+  # ostree python bindings which unfortunately cannot be installed
+  # with pip into your sandbox
+  virtualenv --system-site-packages -p python3 sandbox
+
+  # Install into the virtualenv using pip inside the virtualenv
+  ./sandbox/bin/pip3 install .
+
+Once you have done the above, you have a completely disposable
+``sandbox`` directory which provides an environment you can enter
+at anytime to use BuildStream. BuildStream man pages should also
+be available when in the virtualenv environment.
+
+To enter the environment, source it's activation script::
+
+  source sandbox/bin/activate
+
+From here, the ``bst`` command is available, run ``bst --help`` or ``man bst``.
+
+The activation script adds a bash function to your environment which you
+can use to exit the sandbox environment, just type ``deactivate`` in the
+shell to deactivate the virtualenv sandbox.
+
+To upgrade to a new version of BuildStream when using virtualenv, just
+remove the ``sandbox`` directory completely and recreate it with a new
+version of BuildStream.
+
+
+Using BuildStream inside Docker
+===============================
+Some of the dependencies needed to use BuildStream are still not available in
+some Linux distributions.
+
+It is also possible that the users don't want to install these dependencies in
+their systems. For these cases, it's possible to use Docker.
+
+Here in this page we are going to explain how to use Docker for developing and
+running BuildStream.
+
+
+Building a Docker container to use BuildStream
+----------------------------------------------
+To create a Docker image ready to use with BuildStream you need to run the
+following command in the top level directory of BuildStream repository.
+
+::
+
+    docker build -t buildstream .
+
+Options explained:
+
+-  ``-t buildstream``: Tag the created container as ``buildstream``
+
+The container created will have BuildStream installed. If you want to run a
+different version, you have to switch to the modified source tree and build the
+container image running the same command, or with a different tag.
+
+
+Running BuildStream tests in Docker
+-----------------------------------
+To run the tests inside a Docker container, we only need to mount the
+repository inside the running container and run the tests. To do this run the
+following command:
+
+::
+
+    docker run -it -u $UID:$EUID -v `pwd`:/bst-src:rw \
+               --privileged -w /bst-src buildstream \
+	       python3 setup.py test
+
+Options explained:
+
+-  ``-it``: Interactive shell and TTY support.
+-  ``-u $UID:$EUID``: Use $UID as user-id and $EUID as group-id when
+   running the container.
+-  ``-v $(pwd):/bst-src:rw``: Mount BuildStream source tree in
+   ``/bst-src`` with RW permissions.
+-  ``--privileged``: To give extra privileges to the container (Needed
+   to run some of the sandbox tests).
+-  ``-w /bst-src``: Switch to the ``/bst-src`` directory when running the
+   container.
+
+
+Using BuildStream in a Docker container
+---------------------------------------
+To use BuildStream build tool you will need to mount inside the container your
+workspace, and a folder that BuildStream will use for temporary data. This way
+we make the temporary data persistent between runs.
+
+Run the following command to run a bash session inside the container:
+
+::
+
+    docker run -it -u $UID:$EUID \
+           -v /path/to/buildstream/workspace:/src:rw \
+	   -v /path/to/buildstream/tmp:/buildstream:rw \
+	   buildstream bash
+
+Options:
+
+-  ``-it``: Interactive shell and TTY support.
+-  ``-u $UID:$EUID``: Use $UID as user-id and $EUID as group-id when
+   running the container.
+-  ``-v /path/to/buildstream/workspace:/src:rw``: Mount your workspace in
+   ``/src`` inside the container.
+-  ``-v /path/to/buildstream/tmp:/buildstream:rw``: Mount a temporary folder
+   where BuildStream stores artifacts, sources, etc.