diff options
author | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-06-16 13:20:40 -0400 |
---|---|---|
committer | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-06-16 16:14:04 -0400 |
commit | 1b88e2c6f0e3b060d7319e69d9ddf45bed98596f (patch) | |
tree | d704d114d1e543914dfd68e48421ece7eda16982 /doc | |
parent | b592a80b0e4e244ce50b2452ffcd655fd843bf81 (diff) | |
download | buildstream-1b88e2c6f0e3b060d7319e69d9ddf45bed98596f.tar.gz |
doc: Adding part 1 of the getting started tutorial
o doc/Makefile: Added new directory to collect rst files from
o doc/examples/first-project: Added the "first-project" example
project.
o doc/source/sessions/first-project-*.html: Added the generated
snippets
o doc/source/using_tutorial.rst: Added the new main tutorial page
o doc/source/tutorial/first-project.rst: Added part 1 of the tutorial here
o tests/examples/first-project.py: Added test for the example project
This is largely based on an example by Javier Jardón, which was
submitted at https://gitlab.com/BuildStream/buildstream/merge_requests/323
Fixes #103
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile | 1 | ||||
-rw-r--r-- | doc/examples/first-project/elements/hello.bst | 13 | ||||
-rw-r--r-- | doc/examples/first-project/hello.world | 0 | ||||
-rw-r--r-- | doc/examples/first-project/project.conf | 8 | ||||
-rw-r--r-- | doc/sessions/first-project.run | 37 | ||||
-rw-r--r-- | doc/source/core_plugins.rst | 1 | ||||
-rw-r--r-- | doc/source/main_using.rst | 1 | ||||
-rw-r--r-- | doc/source/sessions/first-project-build.html | 50 | ||||
-rw-r--r-- | doc/source/sessions/first-project-checkout.html | 19 | ||||
-rw-r--r-- | doc/source/sessions/first-project-init.html | 8 | ||||
-rw-r--r-- | doc/source/sessions/first-project-ls.html | 8 | ||||
-rw-r--r-- | doc/source/sessions/first-project-show.html | 14 | ||||
-rw-r--r-- | doc/source/sessions/first-project-touch.html | 6 | ||||
-rw-r--r-- | doc/source/tutorial/first-project.rst | 117 | ||||
-rw-r--r-- | doc/source/using_tutorial.rst | 11 |
15 files changed, 294 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile index ffccba7f1..70df67184 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -104,6 +104,7 @@ html devhelp: templates sessions PYTHONPATH=$(CURDIR)/../buildstream/plugins \ $(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" \ $(wildcard source/*.rst) \ + $(wildcard source/tutorial/*.rst) \ $(wildcard source/examples/*.rst) \ $(wildcard source/elements/*.rst) \ $(wildcard source/sources/*.rst) diff --git a/doc/examples/first-project/elements/hello.bst b/doc/examples/first-project/elements/hello.bst new file mode 100644 index 000000000..d23ebc7b6 --- /dev/null +++ b/doc/examples/first-project/elements/hello.bst @@ -0,0 +1,13 @@ +kind: import + +# Use a local source to stage our file +sources: +- kind: local + path: hello.world + +# Configure the import element +config: + + # Place the content staged by sources at the + # root of the output artifact + target: / diff --git a/doc/examples/first-project/hello.world b/doc/examples/first-project/hello.world new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/doc/examples/first-project/hello.world diff --git a/doc/examples/first-project/project.conf b/doc/examples/first-project/project.conf new file mode 100644 index 000000000..2182d35a1 --- /dev/null +++ b/doc/examples/first-project/project.conf @@ -0,0 +1,8 @@ +# Unique project name +name: first-project + +# Required BuildStream format version +format-version: 9 + +# Subdirectory where elements are stored +element-path: elements diff --git a/doc/sessions/first-project.run b/doc/sessions/first-project.run new file mode 100644 index 000000000..f2500a9d0 --- /dev/null +++ b/doc/sessions/first-project.run @@ -0,0 +1,37 @@ +# Re-create project.conf using `bst init` +remove-files: + - ../examples/first-project/project.conf + - ../examples/first-project/here + +commands: +# Use bst init to create the project.conf +- directory: ../examples/first-project + output: ../source/sessions/first-project-init.html + command: init --project-name first-project + +# Use bst init to create the project.conf +- directory: ../examples/first-project + output: ../source/sessions/first-project-touch.html + command: touch hello.world + fake-output: '' + +# Capture a build output +- directory: ../examples/first-project + output: ../source/sessions/first-project-build.html + command: build hello.bst + +# Capture a show output +- directory: ../examples/first-project + output: ../source/sessions/first-project-show.html + command: show hello.bst + +# Checkout the output +- directory: ../examples/first-project + output: ../source/sessions/first-project-checkout.html + command: checkout hello.bst here + +# Checkout the output +- directory: ../examples/first-project + output: ../source/sessions/first-project-ls.html + command: ls ./here + fake-output: hello.world diff --git a/doc/source/core_plugins.rst b/doc/source/core_plugins.rst index e038c2ef9..36da4a6cf 100644 --- a/doc/source/core_plugins.rst +++ b/doc/source/core_plugins.rst @@ -1,4 +1,5 @@ +.. _plugins: Plugin specific documentation ============================= diff --git a/doc/source/main_using.rst b/doc/source/main_using.rst index dc0f5e69b..d5053747c 100644 --- a/doc/source/main_using.rst +++ b/doc/source/main_using.rst @@ -7,6 +7,7 @@ This section details how to use the BuildStream command line interface and work .. toctree:: :maxdepth: 2 + using_tutorial using_examples using_config using_commands diff --git a/doc/source/sessions/first-project-build.html b/doc/source/sessions/first-project-build.html new file mode 100644 index 000000000..e3766a73b --- /dev/null +++ b/doc/source/sessions/first-project-build.html @@ -0,0 +1,50 @@ +<!-- + WARNING: This file was generated with bst2html.py +--> +<div class="highlight" style="font-size:x-small"><pre> +<span style="color:#C4A000;font-weight:bold">user@host</span>:<span style="color:#3456A4;font-weight:bold">~/first-project</span>$ bst build hello.bst + +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Build +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Checking sources +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Checking sources + +<span style="color:#C4A000"><span style="">BuildStream Version 1.1.3+140.g182d7d0f.dirty +</span></span><span style="color:#06989A"><span style="opacity:0.5"> Session Start: </span></span><span style="color:#C4A000">Saturday, 16-06-2018 at 13:03:19</span> +<span style="color:#06989A"><span style="opacity:0.5"> Project: </span></span><span style="color:#C4A000">first-project (/home/user/first-project)</span> +<span style="color:#06989A"><span style="opacity:0.5"> Targets: </span></span><span style="color:#C4A000">hello.bst</span> + +<span style="color:#C4A000"><span style="">User Configuration +</span></span><span style="color:#06989A"><span style="opacity:0.5"> Configuration File: </span></span><span style="color:#C4A000">/home/user/.config/buildstream.conf</span> +<span style="color:#06989A"><span style="opacity:0.5"> Log Files: </span></span><span style="color:#C4A000">/home/user/.cache/buildstream/logs</span> +<span style="color:#06989A"><span style="opacity:0.5"> Source Mirrors: </span></span><span style="color:#C4A000">/home/user/.cache/buildstream/sources</span> +<span style="color:#06989A"><span style="opacity:0.5"> Build Area: </span></span><span style="color:#C4A000">/home/user/.cache/buildstream/build</span> +<span style="color:#06989A"><span style="opacity:0.5"> Artifact Cache: </span></span><span style="color:#C4A000">/home/user/.cache/buildstream/artifacts</span> +<span style="color:#06989A"><span style="opacity:0.5"> Strict Build Plan: </span></span><span style="color:#C4A000">Yes</span> +<span style="color:#06989A"><span style="opacity:0.5"> Maximum Fetch Tasks: </span></span><span style="color:#C4A000">10</span> +<span style="color:#06989A"><span style="opacity:0.5"> Maximum Build Tasks: </span></span><span style="color:#C4A000">4</span> +<span style="color:#06989A"><span style="opacity:0.5"> Maximum Push Tasks: </span></span><span style="color:#C4A000">4</span> +<span style="color:#06989A"><span style="opacity:0.5"> Maximum Network Retries: </span></span><span style="color:#C4A000">2</span> + +<span style="color:#C4A000"><span style="">Pipeline +</span></span><span style="color:#4E9A06"> buildable</span> <span style="color:#C4A000">838d7c13baadb04d5a95ac8c4623480ec8bb70e8b5cf6c9f7e94c9bbc60ca182</span> <span style="color:#3465A4"><span style="">hello.bst</span></span> +<span style="color:#06989A"><span style="opacity:0.5">=============================================================================== +</span></span><span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">838d7c13</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">build</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">hello.bst </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span><span style="color:#C4A000"><span style="opacity:0.5">first-project/hello/838d7c13-build.769.log</span></span> +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">838d7c13</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">build</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">hello.bst </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Staging sources +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">838d7c13</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">build</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">hello.bst </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Staging sources +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">838d7c13</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">build</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">hello.bst </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Caching artifact +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">838d7c13</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">build</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">hello.bst </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Caching artifact +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">838d7c13</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000">build</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">hello.bst </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span><span style="color:#C4A000"><span style="opacity:0.5">first-project/hello/838d7c13-build.769.log</span></span> +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Build + +<span style="color:#C4A000"><span style="">Pipeline Summary +</span></span><span style="color:#06989A"><span style="opacity:0.5"> Total: </span></span><span style="color:#C4A000">1</span> +<span style="color:#06989A"><span style="opacity:0.5"> Session: </span></span><span style="color:#C4A000">1</span> +<span style="color:#06989A"><span style="opacity:0.5"> Fetch Queue: </span></span><span style="color:#C4A000">processed </span><span style="color:#4E9A06">0</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">skipped </span><span style="color:#C4A000">1</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">failed </span><span style="color:#CC0000"><span style="opacity:0.5">0</span></span> +<span style="color:#06989A"><span style="opacity:0.5"> Build Queue: </span></span><span style="color:#C4A000">processed </span><span style="color:#4E9A06">1</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">skipped </span><span style="color:#C4A000">0</span><span style="color:#06989A"><span style="opacity:0.5">, </span></span><span style="color:#C4A000">failed </span><span style="color:#CC0000"><span style="opacity:0.5">0</span></span> +</pre></div> diff --git a/doc/source/sessions/first-project-checkout.html b/doc/source/sessions/first-project-checkout.html new file mode 100644 index 000000000..2b994e0c2 --- /dev/null +++ b/doc/source/sessions/first-project-checkout.html @@ -0,0 +1,19 @@ +<!-- + WARNING: This file was generated with bst2html.py +--> +<div class="highlight" style="font-size:x-small"><pre> +<span style="color:#C4A000;font-weight:bold">user@host</span>:<span style="color:#3456A4;font-weight:bold">~/first-project</span>$ bst checkout hello.bst here + +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Staging dependencies +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Staging dependencies +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Integrating sandbox +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Integrating sandbox +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Checking out files in here +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Checking out files in here +</pre></div> diff --git a/doc/source/sessions/first-project-init.html b/doc/source/sessions/first-project-init.html new file mode 100644 index 000000000..ba29791fa --- /dev/null +++ b/doc/source/sessions/first-project-init.html @@ -0,0 +1,8 @@ +<!-- + WARNING: This file was generated with bst2html.py +--> +<div class="highlight" style="font-size:x-small"><pre> +<span style="color:#C4A000;font-weight:bold">user@host</span>:<span style="color:#3456A4;font-weight:bold">~/first-project</span>$ bst init --project-name first-project + +Created project.conf at: /home/user/first-project/project.conf +</pre></div> diff --git a/doc/source/sessions/first-project-ls.html b/doc/source/sessions/first-project-ls.html new file mode 100644 index 000000000..97e7f16dc --- /dev/null +++ b/doc/source/sessions/first-project-ls.html @@ -0,0 +1,8 @@ +<!-- + WARNING: This file was generated with bst2html.py +--> +<div class="highlight" style="font-size:x-small"><pre> +<span style="color:#C4A000;font-weight:bold">user@host</span>:<span style="color:#3456A4;font-weight:bold">~/first-project</span>$ ls ./here + +hello.world +</pre></div> diff --git a/doc/source/sessions/first-project-show.html b/doc/source/sessions/first-project-show.html new file mode 100644 index 000000000..aa3c8b8f7 --- /dev/null +++ b/doc/source/sessions/first-project-show.html @@ -0,0 +1,14 @@ +<!-- + WARNING: This file was generated with bst2html.py +--> +<div class="highlight" style="font-size:x-small"><pre> +<span style="color:#C4A000;font-weight:bold">user@host</span>:<span style="color:#3456A4;font-weight:bold">~/first-project</span>$ bst show hello.bst + +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading pipeline +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving pipeline +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state +<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state +<span style="color:#75507B"> cached</span> <span style="color:#C4A000">838d7c13baadb04d5a95ac8c4623480ec8bb70e8b5cf6c9f7e94c9bbc60ca182</span> <span style="color:#3465A4"><span style="">hello.bst</span></span> +</pre></div> diff --git a/doc/source/sessions/first-project-touch.html b/doc/source/sessions/first-project-touch.html new file mode 100644 index 000000000..a7e0338d6 --- /dev/null +++ b/doc/source/sessions/first-project-touch.html @@ -0,0 +1,6 @@ +<!-- + WARNING: This file was generated with bst2html.py +--> +<div class="highlight" style="font-size:x-small"><pre> +<span style="color:#C4A000;font-weight:bold">user@host</span>:<span style="color:#3456A4;font-weight:bold">~/first-project</span>$ touch hello.world +</pre></div> diff --git a/doc/source/tutorial/first-project.rst b/doc/source/tutorial/first-project.rst new file mode 100644 index 000000000..9112350f0 --- /dev/null +++ b/doc/source/tutorial/first-project.rst @@ -0,0 +1,117 @@ + +Your first project +================== +To get a feel for the basics, we'll start with the most basic BuildStream project we +could think of. + +.. note:: + + This example is distributed with BuildStream + in the `doc/examples/first-project + <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/first-project>`_ + subdirectory. + + +Creating the project +-------------------- +First, lets create the project itself using the convenience :ref:`bst init <invoking_init>` +command to create a little project structure: + +.. raw:: html + :file: ../sessions/first-project-init.html + +This will give you a :ref:`project.conf <projectconf>` which will look like this: + +.. literalinclude:: ../../examples/first-project/project.conf + :language: yaml + +The :ref:`project.conf <projectconf>` is a central point of configuration +for your BuildStream project. + + +Add some content +---------------- +BuildStream processes directory trees as input and output, +so let's just create a ``hello.world`` file for the project +to have. + +.. raw:: html + :file: ../sessions/first-project-touch.html + + +Declare the element +------------------- +Here we're going to declare a simple :mod:`import <elements.import>` element +which will import the ``hello.world`` file we've created in the previous step. + +Create ``elements/hello.bst`` with the following content: + +.. literalinclude:: ../../examples/first-project/elements/hello.bst + :language: yaml + + +The source +~~~~~~~~~~ +The :mod:`local <sources.local>` source used by the ``hello.bst`` element, +can be used to access files or directories which are stored in the same repository +as your BuildStream project. The ``hello.bst`` element uses the :mod:`local <sources.local>` +source to stage our local ``hello.world`` file. + + +The element +~~~~~~~~~~~ +The :mod:`import <elements.import>` element can be used to simply add content +directly to the output artifacts. In this case, it simply takes the ``hello.world`` file +provided by it's source and stages it directly to the artifact output root. + +.. tip:: + + In this example so far we've used two plugins, the :mod:`local <sources.local>` + source and the :mod:`import <elements.import>` element. + + You can always browse the documentation for all plugins in + the :ref:`plugins section <plugins>` of the manual. + + +Build the element +----------------- +In order to carry out the activities of the :mod:`import <elements.import>` element +we've declared, we're going to have to ask BuildStream to *build*. + +This process will collect all of the sources required for the specified ``hello.bst`` +and get the backing :mod:`import <elements.import>` element to generate an *artifact* +for us. + +.. raw:: html + :file: ../sessions/first-project-build.html + +Now the artifact is ready. + +Using ``bst show``, we can observe that the artifact's state, which was reported +as ``buildable`` in the ``bst build`` command above, has now changed to ``cached``: + +.. raw:: html + :file: ../sessions/first-project-show.html + + +Observe the output +------------------ +Now that we've finished building, we can checkout the output of the +artifact we've created: + +.. raw:: html + :file: ../sessions/first-project-checkout.html + +And observe that the file we expect is there: + +.. raw:: html + :file: ../sessions/first-project-ls.html + + +Summary +------- +In this section we've created our first BuildStream project from +scratch, but it doesnt do much. + +We've observed the general structure of a BuildStream project, +and we've run our first build. diff --git a/doc/source/using_tutorial.rst b/doc/source/using_tutorial.rst new file mode 100644 index 000000000..8a0116d04 --- /dev/null +++ b/doc/source/using_tutorial.rst @@ -0,0 +1,11 @@ + +Tutorial +======== +This is a step by step walkthrough meant help the user quickly get +familiar with the fundamentals of creating and using BuildStream +projects. + +.. toctree:: + :maxdepth: 1 + + tutorial/first-project |