Merge branch 'invoking_page_changes'

6 files changed, 310 insertions, 11 deletions

diff --git a/doc/source/buildproject.rst b/doc/source/buildproject.rst
new file mode 100644
index 000000000..d9404e545
--- /dev/null
+++ b/doc/source/buildproject.rst
@@ -0,0 +1,61 @@
+.. _buildproject:
+
+Building a basic project
+====
+
+This Section assumes you have installed Buildstream already.
+
+If not, go to :ref:`installing`
+
+Or :ref:`docker`
+
+
+Setup
+----
+
+If using docker, run::
+
+  bst-here 
+
+in the directory you want to use
+
+then install wget or some other download tool
+
+----
+
+If not already installed, install `git`
+
+This example will be using `gnome-modulesets`, but this will apply to any buildable repo
+
+git clone: http://gnome7.codethink.co.uk/gnome-modulesets.git/
+ 
+Then move into the repo
+
+Building
+----
+
+Find the .bst file that you want to build
+
+In this case, we will be using `gedit.bst` in elements/core 
+
+from the root of the project repo run:
+
+    ``bst`` :ref:`invoking_build` ``core/gedit.bst``
+
+To build the project.
+
+If you get an error requesting the use of ``bst track``
+
+run:
+    ``bst`` :ref:`invoking_track` ``--deps all core/gedit.bst``
+
+This will update all dependencies and should allow the build to pass.
+
+Run the build command again and this time it should pass.
+
+Once this is done, you can run:
+    ``bst`` :ref:`invoking_shell` ``core/gedit.bst``
+
+Which will create a shell where gedit has been built.
+once the shell has been started, running the `gedit` command should begin the application
+
diff --git a/doc/source/createproject.rst b/doc/source/createproject.rst
new file mode 100644
index 000000000..7d5599349
--- /dev/null
+++ b/doc/source/createproject.rst
@@ -0,0 +1,137 @@
+.. _createproject:
+
+Creating a basic project
+====
+
+This Section assumes you have installed Buildstream already.
+
+If not, go to :ref:`install`
+
+Or :ref:`docker`
+
+This section will be using files from: 
+
+https://gitlab.com/BuildStream/buildstream/tree/master/integration-tests/cmake-test/
+
+Setup
+----
+
+If using docker, run::
+
+  bst-here 
+
+in the directory you want to use
+
+Create a project directory and in it create the following directories:
+    elements, elements/dependencies, keys, src
+
+install wget or some other download tool
+
+----
+
+For this example we will be using cmake-test,
+as it is a relatively small and simple project to build
+
+Download https://gitlab.com/BuildStream/buildstream/raw/master/integration-tests/cmake-test/src/step7.tar.gz
+
+This should provide you with step7.tar.gz
+
+Move step7.tar.gz to src
+
+----
+
+Download https://gitlab.com/BuildStream/buildstream/raw/master/integration-tests/cmake-test/keys/gnome-sdk.gpg
+
+This should provide you with gnome-sdk.gpg
+
+Move gnome-sdk.gpg to keys
+
+Creating the project files
+----
+
+Project.conf
+~~~~
+
+In the root of the project directory create a file called project.conf containing::
+
+  name: ProjectName  #The name you want to give to your project
+  element-path: elementsPath #The path to the "elements" directory
+  aliases:
+    name:url #This is used so you can moderate the URLs/Repos used by your build. 
+             #This way, they can be modified in a single place instead of multiple
+
+step7.bst
+~~~~
+
+In the elements directory Create a file called step7.bst containing::
+
+  kind: cmake
+  description: Cmake test
+  
+  depends:
+    - filename: dependencies/base-platform.bst
+      type: build
+    - filename: dependencies/base-sdk.bst
+      type: build
+  
+  sources:
+    - kind: tar
+      url: file:/src/step7.tar.gz
+      ref: 9591707afbae77751730b4af4c52a18b1cdc4378237bc64055f099bc95c330db
+  
+:ref:`format_kind`
+
+:ref:`format_depends`
+
+:ref:`format_sources`
+
+.. this is done until i can find a better way of incorperating hyperlinks into sourcecode blocks
+
+base-sdk.bst
+~~~~
+
+In the elements/dependencies directory Create a file called base-sdk.bst containing::
+
+  kind: import
+  description: Import the base freedesktop SDK
+  sources:
+  - kind: ostree
+    url: gnomesdk:repo/
+    gpg-key: keys/gnome-sdk.gpg
+    track: runtime/org.freedesktop.BaseSdk/x86_64/1.4
+    ref: 0d9d255d56b08aeaaffb1c820eef85266eb730cb5667e50681185ccf5cd7c882
+  config:
+    source: files
+    target: usr
+
+:ref:`format_config`
+
+base-platform.bst
+~~~~
+
+In the elements/dependencies directory Create a file called base-platform.bst containing::
+
+  kind: import
+  description: Import the base freedesktop platform
+  sources:
+  - kind: ostree
+    url: gnomesdk:repo/
+    gpg-key: keys/gnome-sdk.gpg
+    track: runtime/org.freedesktop.BasePlatform/x86_64/1.4
+    ref: c9d09b7250a12ef09d95952fc4f49a35e5f8c2c1dd7141b7eeada4069e6f6576
+  config:
+    source: files
+  public:
+    bst:
+      integration-commands:
+      - ldconfig
+
+:ref:`format_public` 
+
+Building
+----
+
+From the project root directory run:
+
+  ``bst`` :ref:`invoking_build` ``step7.bst``
+
diff --git a/doc/source/format.rst b/doc/source/format.rst
index 7e4638e1c..66a9d3f20 100644
--- a/doc/source/format.rst
+++ b/doc/source/format.rst
@@ -53,6 +53,7 @@ details here in order to have a more complete initial example.
 
 Let's break down the above and give a brief explanation of what these attributes mean.
 
+.. _format_kind:
 
 Kind
 ~~~~
@@ -72,6 +73,7 @@ To refer to a third party plugin, prefix the plugin with its package, for exampl
 
    kind: buildstream-plugins:dpkg_build
 
+.. _format_depends:
 
 Depends
 ~~~~~~~
@@ -88,6 +90,7 @@ definitions may depend on other elements by specifying the project relative path
 to the elements on which they depend here. See `Dependencies`_ for more information
 on the dependency model.
 
+.. _format_sources:
 
 Sources
 ~~~~~~~
@@ -132,6 +135,7 @@ Asides from the common ``kind`` and ``directory`` attributes which may be applie
 Sources, refer to the Source specific documentation for meaningful attributes for the
 particular Source.
 
+.. _format_variables:
 
 Variables
 ~~~~~~~~~
@@ -147,6 +151,7 @@ declared and overridden in the :ref:`projectconf`
 
 See `Using Variables`_ below for a more in depth discussion on variables in BuildStream.
 
+.. _format_environment:
 
 Environment
 ~~~~~~~~~~~
@@ -164,6 +169,7 @@ build instructions are run for this element.
 
 Environment variables can also be declared and overridden in the :ref:`projectconf`
 
+.. _format_config:
 
 Config
 ~~~~~~
diff --git a/doc/source/index.rst b/doc/source/index.rst
index e62e23492..be355bd41 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -24,7 +24,8 @@ Installing
 * :ref:`installing`
 * :ref:`docker`
 * :ref:`artifacts`
-
+* :ref:`createproject`
+* :ref:`buildproject`
 
 Running
 -------
diff --git a/doc/source/install.rst b/doc/source/install.rst
index 45beb716c..ce3e886b6 100644
--- a/doc/source/install.rst
+++ b/doc/source/install.rst
@@ -17,8 +17,20 @@ BuildStream requires the following base system requirements:
 
 * python3 >= 3.4
 * ruamel.yaml python library
-* PyGObject introspection bindings
 * OSTree >= v2017.8 with introspection data
+* build-essential
+* git
+* gir1.2-ostree-1.0
+* bubblewrap
+* dh-autoreconf
+* libglib2.0-dev
+* bison
+* liblzma-dev
+* e2fslibs-dev
+* gobject-introspection
+* libostree-dev
+* libgirepository1.0-dev
+
 
 Note that ``ruamel.yaml`` is a pure python library which is normally
 obtainable via pip, however there seems to be some problems with installing
@@ -29,7 +41,6 @@ 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.
@@ -65,17 +76,52 @@ At this point you should be able to get the system requirements with::
 
 Debian Buster 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-dev python3-pip git \
-      python3-gi gir1.2-ostree-1.0 ostree \
-      bubblewrap python3-ruamel.yaml
 
+For debian unstable or testing, the following line should be enough
+to get most of the base system requirements installed::
+
+  sudo apt install build-essential \
+      python3 \
+      python3-dev \
+      python3-pip \
+      git \
+      python3-gi \
+      gir1.2-ostree-1.0 \
+      bubblewrap \
+      ruamel.yaml \
+      dh-autoreconf \
+      libglib2.0-dev \
+      bison \
+      liblzma-dev \
+      e2fslibs-dev \
+      gobject-introspection \
+      libostree-dev \
+      libgirepository1.0-dev 
+
+To install ostree:
+
+Go to the directory you want the ostree repo stored in::
+
+   git clone https://github.com/ostreedev/ostree.git 
+   cd ostree
+   sudo mkdir /opt/ostree
+   sudo chown $USERNAME /opt/ostree
+   ./autogen.sh
+   ./configure --prefix=/opt/ostree
+   make
+   sudo make install
+
+we need to add those install paths to our path and as we have installed object introspection
+and built ostree with this capability we must also specify that on our path.
+
+So you must add::
+
+   PATH=/opt/ostree/bin:$PATH
+export GI_TYPELIB_PATH=/opt/ostree/lib/girepository-1.0/
 
 Fedora
 ~~~~~~
+
 For recent fedora systems, the following line should get you the system
 requirements you need::
 
diff --git a/doc/source/invoking.rst b/doc/source/invoking.rst
index ca14f24bd..419ac1dd9 100644
--- a/doc/source/invoking.rst
+++ b/doc/source/invoking.rst
@@ -5,4 +5,52 @@ Invoking BuildStream
 
 .. click:: buildstream._frontend.main:cli
    :prog: bst
-   :show-nested:
+
+.. _invoking_build:
+
+.. click:: buildstream._frontend.main:build
+   :prog: build
+
+.. click:: buildstream._frontend.main:fetch
+   :prog: fetch
+
+.. _invoking_track:
+
+.. click:: buildstream._frontend.main:track
+   :prog: track
+
+.. click:: buildstream._frontend.main:pull
+   :prog: pull
+
+.. click:: buildstream._frontend.main:push
+   :prog: push
+
+.. click:: buildstream._frontend.main:show
+   :prog: show
+
+.. _invoking_shell:
+
+.. click:: buildstream._frontend.main:shell
+   :prog: shell 
+
+.. click:: buildstream._frontend.main:checkout
+   :prog: checkout
+
+.. click:: buildstream._frontend.main:source_bundle
+   :prog: source bundle
+
+.. click:: buildstream._frontend.main:workspace
+   :prog: workspace
+
+.. click:: buildstream._frontend.main:workspace_open
+   :prog: workspace open
+
+.. click:: buildstream._frontend.main:workspace_close
+   :prog: workspace close
+
+.. click:: buildstream._frontend.main:workspace_reset
+   :prog: workspace reset
+
+.. click:: buildstream._frontend.main:workspace_list
+   :prog: workspace list
+