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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
.. _examples_out-of-source-build.rst:
Building out of source
======================
Intro
-----
This example aims to:
* Give a basic overview of how out of source builds work. This is done by
collecting the relevant bits of information spread across different sections
of the documentation that tend to group information by element rather than
task.
* Give Examples of how to use out of source builds.
Buildstream aims to make out of source builds easy and consistent across as
many build systems as possible. However it should be noted that not all build
systems support `out of source builds`.
Key Variables
-------------
Out of source builds are configured by setting:
* ``directory`` of the source, this sets the source to extract to a folder in
the build root.
* ``command-subdir`` variable, sets the directory were the build commands
will be run.
* ``conf-root`` variable, tells the configuration tool were to find the root of
the source code.
``conf-root`` is given to the configuration tool which is run in
``command-subdir``. It can either be given as a relative path from
``command-subdir`` to the location of the source code. Or as an absolute
location.
By setting ``conf-root`` as a absolute path we can change ``command-subdir``
with out having to change ``conf-root``.
If a absolute path is given it must be from the root of the sandbox.
To specify a absolute path from the root of the build-root the build-root
variable can be used eg. ``conf-root`` can be set to ``"%{build-root}/Source"``
to specify the ``Source`` folder in the root of the build-root.
These variables can be use for many of the buildstream build element kinds.
Indeed converting to out of source builds should be as simple as adding these
variables to the individual bst files and in some circumstance most of the
variables could be set at a project level.
Examples
--------
The out of source examples can be found in the buildstream source code in
``doc/examples/out-of-source`` folder in the buildstream source. The two cmake
elements we will use as examples are `sourceroot.bst` and `subfolder.bst`.
It is very simple to create a build element that loads a source in to the
`build-root` and then uses the standard build tools to build the project in the
same folder. Buildstream has lots of build element plugs so that a new element
may only need to set its `kind` to the relevant build system and then define a
source, the `sourceroot.bst` example element takes a cmake exmaple and expands
it to a out of source build.
An alternative build elements might build in a sub folder of the source. The
`hello.bst` element in the `autotools` example dose this. And a out of source
version is given in the `subfolder.bst` element of the out of source example
project.
Build project defined in source root
------------------------------------
This example points cmake at the root of the source.
In this example, the CMakeLis.txt in the root folder of the source
causes the helloworld program to state that it was build from the root of the
source project when called.
To make the software build in a folder outside of the source code we set the
source to be in a sub folder of the build-root folder rather than in its root,
in our case this folder will be called ``source``.
The build tools are then set to run a separate folder in the build-root folder,
this will be called ``build``. We must then tell the build tools were to
find the source code, this is done with the ``conf-root`` variable.
This is done by:
* Setting the sources ``directory`` property to ``Source``
* Setting the element variable ``command-subdir`` to ``build``
* Setting the element variable ``conf-root`` to ``"%{build-root}/Source"``
``sourceroot.bst``
~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../examples/out-of-source-build/elements/sourceroot.bst
:language: yaml
We can then use the ``bst show`` command to see how variable like ``conf-root``
are expanded.
.. raw:: html
:file: ../sessions/out-of-source-build-show-variables.html
Using a workspace or a shell with `--build` can be used to see the folder
structure that gets created. When bst shell is launched it runs in the
``command-subdir`` directory. If ``ls ..`` is run we can see that the build-root
now contains the ``build`` folder and the ``Source`` folder.
.. raw:: html
:file: ../sessions//out-of-source-build-shell-ls.html
Build project defined in source subdirectory
--------------------------------------------
This example points cmake at he `main` directory inside the source.
In this example, the CMakeLis.txt in the folder main in the root of the
source causes the helloworld program to state that it was build from a subfolder
of the source project when called.
To make the software build in a folder outside of the source code we set the
source to be in a sub folder of the build-root folder rather than in its root,
in our case this folder will be called ``source``.
The build tools are then set to run a separate folder in the build-root folder,
this will be called ``build``. We must then tell the build tools were to
find the source code, this is done with the ``conf-root`` variable.
Unlike the previous example we need ``conf-root`` to point the sub directory of
the source project rather than the root.
This is done by:
* Setting the sources ``directory`` property to ``Source``
* Setting the element variable ``command-subdir`` to ``build``
* Setting the element variable ``conf-root`` to
``"%{build-root}/Source/main"``
``subfolder.bst``
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../examples/out-of-source-build/elements/subfolder.bst
:language: yaml
Run the hello world program
~~~~~~~~~~~~~~~~~~~~~~~~~~~
We can see the output of the two different binaries created from the same
source by invoking the shell of the respective elements with the new programs
name.
When the binary from the build that included the file that defined the extra build
flag ``FULL_PROJECT`` is run, we get the following output:
.. raw:: html
:file: ../sessions/out-of-source-build-shell.html
When the binary from the build that pointed to the CMakeList.txt that
just adds the source without defining any extra build flags is run, we get the
following output:
.. raw:: html
:file: ../sessions/out-of-source-build-shell-subfolder.html
|
