tutorials: Add workspaces tutorial

            $(wildcard source/advanced-features/*.rst) \

	    $(wildcard source/examples/*.rst) \

	    $(wildcard source/elements/*.rst) \

	    $(wildcard source/sources/*.rst)

	    $(wildcard source/sources/*.rst) \

	    $(wildcard source/developing/*.rst)

	@echo

	@echo "Build of $@ finished, output: $(CURDIR)/$(BUILDDIR)/$@"

# Makefile for Sphinx documentation

# Unique project name

name: running-commands

name: developing 

# Required BuildStream format version

format-version: 9

.. _developing_workspaces:

Workspaces

==========

In this section we will cover the use of BuildStream's workspaces feature when devloping on a 

BuildStream project.

.. note::

   This example is distributed with BuildStream

   in the `doc/examples/developing

   <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/developing>`_

   subdirectory.

We will start with the project used in the :ref:`running commands <tutorial_running_commands>`

tutorial. Recall the element hello.bst, which builds the bellow C file:

.. literalinclude:: ../../examples/developing/files/src/hello.c

   :language: c

Suppose we now want to alter the functionality of the *hello* command. We can

make changes to the source code of Buildstream elements by making use of

BuildStream's workspace command.

Opening a workspace

-------------------

First we need to open a workspace, we can do this by running

.. raw:: html

   :file: ../sessions/developing-workspace-open.html

This command has created the workspace_hello directory in which you can see

the source for the hello.bst element, i.e. hello.c and the corresponding

makefile.

You can view existing workspaces using

.. raw:: html

   :file: ../sessions/developing-workspace-list.html

Making code changes

-------------------

Let's say we want to alter the message printed when the hello command is run.

We can open workspace_hello/hello.c and make the following change:

.. literalinclude:: ../../examples/developing/update.patch

    :language: diff

Now, rebuild the hello.bst element

.. raw:: html

   :file: ../sessions/developing-build-after-changes.html

Now running the hello command using bst shell:

.. raw:: html

   :file: ../sessions/developing-shell-after-changes.html

This gives us the new message we changed in hello.c.

From this point we have several options. If the source is under version control

we can commit our changes and push them to the remote repository.

Closing your workspace

----------------------

If we want to close the workspace and come back to our changes later, we can

.. raw:: html

   :file: ../sessions/developing-close-workspace.html

We can then reopen the workspace later using:

.. raw:: html

   :file: ../sessions/developing-reopen-workspace.html

The --no-checkout option tells BuildStream not to check the source out but to

instead hard-link to the workspace_hello directory.

Alternatively, if we wish to discard the changes we can use

.. raw:: html

   :file: ../sessions/developing-reset-workspace.html

This resets the workspace to its original state.

To discard the workspace completely we can do:

.. raw:: html

   :file: ../sessions/developing-discard-workspace.html

This will close the workspace and completely remove the workspace_hello

directory.

   :maxdepth: 2

   using_tutorial

   using_developing

   using_advanced_features

   using_examples

   using_config

Developing with BuildStream

===========================

This is an introduction to the  step by step walkthrough aimed at helping users

get to grips with the process of developing a project using BuildStream. 

.. toctree::

   :numbered:

   :maxdepth: 1

   developing/workspaces.rst