1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
.. _tutorial_first_project:
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:
``project.conf``
~~~~~~~~~~~~~~~~
.. 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:
``elements/hello.bst``
~~~~~~~~~~~~~~~~~~~~~~
.. 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 :ref:`bst show <invoking_show>`, we can observe that the artifact's state, which was reported
as ``buildable`` in the :ref:`bst build <invoking_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 using :ref:`bst checkout <invoking_checkout>`
.. 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.
|
