summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-07-31 10:00:02 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-16 18:14:08 +0100
commite3b76c8fc370833a623791cec6e805158d35e9d1 (patch)
tree9ad3df8166ed0a79dee3a454dcba53281f375f2f /bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst
parent4324c6e0716915c4d375805ce695a9eedb0fa010 (diff)
downloadpoky-e3b76c8fc370833a623791cec6e805158d35e9d1.tar.gz
bitbake: sphinx: last manual round of fixes/improvements
Review all pages, and fix up for formatting which was not covered by pandoc, such as some links and code block sections. (Bitbake rev: d99760cc687cc9c24d6d9a1c49fa094574476e0c) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst')
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst417
1 files changed, 235 insertions, 182 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst
index d64f6e00ca..e3fd321588 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst
@@ -18,21 +18,28 @@ it.
18Obtaining BitBake 18Obtaining BitBake
19================= 19=================
20 20
21See the "`Obtaining BitBake <#obtaining-bitbake>`__" section for 21See the :ref:`bitbake-user-manual/bitbake-user-manual-hello:obtaining bitbake` section for
22information on how to obtain BitBake. Once you have the source code on 22information on how to obtain BitBake. Once you have the source code on
23your machine, the BitBake directory appears as follows: $ ls -al total 23your machine, the BitBake directory appears as follows: ::
24100 drwxrwxr-x. 9 wmat wmat 4096 Jan 31 13:44 . drwxrwxr-x. 3 wmat wmat 24
254096 Feb 4 10:45 .. -rw-rw-r--. 1 wmat wmat 365 Nov 26 04:55 AUTHORS 25 $ ls -al
26drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 bin drwxrwxr-x. 4 wmat wmat 26 total 100
274096 Jan 31 13:44 build -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 27 drwxrwxr-x. 9 wmat wmat 4096 Jan 31 13:44 .
28ChangeLog drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 classes drwxrwxr-x. 28 drwxrwxr-x. 3 wmat wmat 4096 Feb 4 10:45 ..
292 wmat wmat 4096 Nov 26 04:55 conf drwxrwxr-x. 3 wmat wmat 4096 Nov 26 29 -rw-rw-r--. 1 wmat wmat 365 Nov 26 04:55 AUTHORS
3004:55 contrib -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING 30 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 bin
31drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 doc -rw-rw-r--. 1 wmat wmat 69 31 drwxrwxr-x. 4 wmat wmat 4096 Jan 31 13:44 build
32Nov 26 04:55 .gitignore -rw-rw-r--. 1 wmat wmat 849 Nov 26 04:55 HEADER 32 -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 ChangeLog
33drwxrwxr-x. 5 wmat wmat 4096 Jan 31 13:44 lib -rw-rw-r--. 1 wmat wmat 33 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 classes
34195 Nov 26 04:55 MANIFEST.in -rw-rw-r--. 1 wmat wmat 2887 Nov 26 04:55 34 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 conf
35TODO 35 drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 contrib
36 -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING
37 drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 doc
38 -rw-rw-r--. 1 wmat wmat 69 Nov 26 04:55 .gitignore
39 -rw-rw-r--. 1 wmat wmat 849 Nov 26 04:55 HEADER
40 drwxrwxr-x. 5 wmat wmat 4096 Jan 31 13:44 lib
41 -rw-rw-r--. 1 wmat wmat 195 Nov 26 04:55 MANIFEST.in
42 -rw-rw-r--. 1 wmat wmat 2887 Nov 26 04:55 TODO
36 43
37At this point, you should have BitBake cloned to a directory that 44At this point, you should have BitBake cloned to a directory that
38matches the previous listing except for dates and user names. 45matches the previous listing except for dates and user names.
@@ -42,18 +49,29 @@ Setting Up the BitBake Environment
42 49
43First, you need to be sure that you can run BitBake. Set your working 50First, you need to be sure that you can run BitBake. Set your working
44directory to where your local BitBake files are and run the following 51directory to where your local BitBake files are and run the following
45command: $ ./bin/bitbake --version BitBake Build Tool Core version 52command: ::
461.23.0, bitbake version 1.23.0 The console output tells you what version 53
54 $ ./bin/bitbake --version
55 BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0
56
57The console output tells you what version
47you are running. 58you are running.
48 59
49The recommended method to run BitBake is from a directory of your 60The recommended method to run BitBake is from a directory of your
50choice. To be able to run BitBake from any directory, you need to add 61choice. To be able to run BitBake from any directory, you need to add
51the executable binary to your binary to your shell's environment 62the executable binary to your binary to your shell's environment
52``PATH`` variable. First, look at your current ``PATH`` variable by 63``PATH`` variable. First, look at your current ``PATH`` variable by
53entering the following: $ echo $PATH Next, add the directory location 64entering the following: ::
65
66 $ echo $PATH
67
68Next, add the directory location
54for the BitBake binary to the ``PATH``. Here is an example that adds the 69for the BitBake binary to the ``PATH``. Here is an example that adds the
55``/home/scott-lenovo/bitbake/bin`` directory to the front of the 70``/home/scott-lenovo/bitbake/bin`` directory to the front of the
56``PATH`` variable: $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH 71``PATH`` variable: ::
72
73 $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH
74
57You should now be able to enter the ``bitbake`` command from the command 75You should now be able to enter the ``bitbake`` command from the command
58line while working from any directory. 76line while working from any directory.
59 77
@@ -74,8 +92,7 @@ example.
74While every attempt is made to explain what is happening during the 92While every attempt is made to explain what is happening during the
75example, the descriptions cannot cover everything. You can find further 93example, the descriptions cannot cover everything. You can find further
76information throughout this manual. Also, you can actively participate 94information throughout this manual. Also, you can actively participate
77in the 95in the :oe_lists:`/g/bitbake-devel`
78http://lists.openembedded.org/mailman/listinfo/bitbake-devel
79discussion mailing list about the BitBake build tool. 96discussion mailing list about the BitBake build tool.
80 97
81.. note:: 98.. note::
@@ -87,36 +104,46 @@ discussion mailing list about the BitBake build tool.
87As stated earlier, the goal of this example is to eventually compile 104As stated earlier, the goal of this example is to eventually compile
88"Hello World". However, it is unknown what BitBake needs and what you 105"Hello World". However, it is unknown what BitBake needs and what you
89have to provide in order to achieve that goal. Recall that BitBake 106have to provide in order to achieve that goal. Recall that BitBake
90utilizes three types of metadata files: `Configuration 107utilizes three types of metadata files:
91Files <#configuration-files>`__, `Classes <#classes>`__, and 108:ref:`bitbake-user-manual/bitbake-user-manual-intro:configuration files`,
92`Recipes <#recipes>`__. But where do they go? How does BitBake find 109:ref:`bitbake-user-manual/bitbake-user-manual-intro:classes`, and
110:ref:`bitbake-user-manual/bitbake-user-manual-intro:recipes`.
111But where do they go? How does BitBake find
93them? BitBake's error messaging helps you answer these types of 112them? BitBake's error messaging helps you answer these types of
94questions and helps you better understand exactly what is going on. 113questions and helps you better understand exactly what is going on.
95 114
96Following is the complete "Hello World" example. 115Following is the complete "Hello World" example.
97 116
981. *Create a Project Directory:* First, set up a directory for the 117#. **Create a Project Directory:** First, set up a directory for the
99 "Hello World" project. Here is how you can do so in your home 118 "Hello World" project. Here is how you can do so in your home
100 directory: $ mkdir ~/hello $ cd ~/hello This is the directory that 119 directory: ::
120
121 $ mkdir ~/hello
122 $ cd ~/hello
123
124 This is the directory that
101 BitBake will use to do all of its work. You can use this directory 125 BitBake will use to do all of its work. You can use this directory
102 to keep all the metafiles needed by BitBake. Having a project 126 to keep all the metafiles needed by BitBake. Having a project
103 directory is a good way to isolate your project. 127 directory is a good way to isolate your project.
104 128
1052. *Run BitBake:* At this point, you have nothing but a project 129#. **Run BitBake:** At this point, you have nothing but a project
106 directory. Run the ``bitbake`` command and see what it does: $ 130 directory. Run the ``bitbake`` command and see what it does: ::
107 bitbake The BBPATH variable is not set and bitbake did not find a 131
108 conf/bblayers.conf file in the expected location. Maybe you 132 $ bitbake
109 accidentally invoked bitbake from the wrong directory? DEBUG: 133 The BBPATH variable is not set and bitbake did not
110 Removed the following variables from the environment: 134 find a conf/bblayers.conf file in the expected location.
111 GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP, 135 Maybe you accidentally invoked bitbake from the wrong directory?
112 GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy, 136 DEBUG: Removed the following variables from the environment:
113 XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL, 137 GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,
114 MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR, 138 GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,
115 GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID, 139 XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,
116 XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS, 140 MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,
117 \_, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH, 141 GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,
118 UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS The 142 XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,
119 majority of this output is specific to environment variables that 143 _, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH,
144 UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS
145
146 The majority of this output is specific to environment variables that
120 are not directly relevant to BitBake. However, the very first 147 are not directly relevant to BitBake. However, the very first
121 message regarding the ``BBPATH`` variable and the 148 message regarding the ``BBPATH`` variable and the
122 ``conf/bblayers.conf`` file is relevant. 149 ``conf/bblayers.conf`` file is relevant.
@@ -128,14 +155,18 @@ Following is the complete "Hello World" example.
128 (``.conf``) or recipe files (``.bb``) at all. BitBake also cannot 155 (``.conf``) or recipe files (``.bb``) at all. BitBake also cannot
129 find the ``bitbake.conf`` file. 156 find the ``bitbake.conf`` file.
130 157
1313. *Setting ``BBPATH``:* For this example, you can set ``BBPATH`` in 158#. **Setting BBPATH:** For this example, you can set ``BBPATH`` in
132 the same manner that you set ``PATH`` earlier in the appendix. You 159 the same manner that you set ``PATH`` earlier in the appendix. You
133 should realize, though, that it is much more flexible to set the 160 should realize, though, that it is much more flexible to set the
134 ``BBPATH`` variable up in a configuration file for each project. 161 ``BBPATH`` variable up in a configuration file for each project.
135 162
136 From your shell, enter the following commands to set and export the 163 From your shell, enter the following commands to set and export the
137 ``BBPATH`` variable: $ BBPATH="projectdirectory" $ export BBPATH Use 164 ``BBPATH`` variable: ::
138 your actual project directory in the command. BitBake uses that 165
166 $ BBPATH="projectdirectory"
167 $ export BBPATH
168
169 Use your actual project directory in the command. BitBake uses that
139 directory to find the metadata it needs for your project. 170 directory to find the metadata it needs for your project.
140 171
141 .. note:: 172 .. note::
@@ -144,28 +175,32 @@ Following is the complete "Hello World" example.
144 ("~") character as BitBake does not expand that character as the 175 ("~") character as BitBake does not expand that character as the
145 shell would. 176 shell would.
146 177
1474. *Run BitBake:* Now that you have ``BBPATH`` defined, run the 178#. **Run BitBake:** Now that you have ``BBPATH`` defined, run the
148 ``bitbake`` command again: $ bitbake ERROR: Traceback (most recent 179 ``bitbake`` command again: ::
149 call last): File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", 180
150 line 163, in wrapped return func(fn, \*args) File 181 $ bitbake
151 "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in 182 ERROR: Traceback (most recent call last):
152 parse_config_file return bb.parse.handle(fn, data, include) File 183 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
153 "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in 184 return func(fn, *args)
154 handle return h['handle'](fn, data, include) File 185 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file
155 "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", 186 return bb.parse.handle(fn, data, include)
156 line 120, in handle abs_fn = resolve_file(fn, data) File 187 File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle
157 "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in 188 return h['handle'](fn, data, include)
158 resolve_file raise IOError("file %s not found in %s" % (fn, bbpath)) 189 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle
159 IOError: file conf/bitbake.conf not found in 190 abs_fn = resolve_file(fn, data)
160 /home/scott-lenovo/hello ERROR: Unable to parse conf/bitbake.conf: 191 File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file
161 file conf/bitbake.conf not found in /home/scott-lenovo/hello This 192 raise IOError("file %s not found in %s" % (fn, bbpath))
162 sample output shows that BitBake could not find the 193 IOError: file conf/bitbake.conf not found in /home/scott-lenovo/hello
194
195 ERROR: Unable to parse conf/bitbake.conf: file conf/bitbake.conf not found in /home/scott-lenovo/hello
196
197 This sample output shows that BitBake could not find the
163 ``conf/bitbake.conf`` file in the project directory. This file is 198 ``conf/bitbake.conf`` file in the project directory. This file is
164 the first thing BitBake must find in order to build a target. And, 199 the first thing BitBake must find in order to build a target. And,
165 since the project directory for this example is empty, you need to 200 since the project directory for this example is empty, you need to
166 provide a ``conf/bitbake.conf`` file. 201 provide a ``conf/bitbake.conf`` file.
167 202
1685. *Creating ``conf/bitbake.conf``:* The ``conf/bitbake.conf`` includes 203#. **Creating conf/bitbake.conf:** The ``conf/bitbake.conf`` includes
169 a number of configuration variables BitBake uses for metadata and 204 a number of configuration variables BitBake uses for metadata and
170 recipe files. For this example, you need to create the file in your 205 recipe files. For this example, you need to create the file in your
171 project directory and define some key BitBake variables. For more 206 project directory and define some key BitBake variables. For more
@@ -173,106 +208,100 @@ Following is the complete "Hello World" example.
173 http://git.openembedded.org/bitbake/tree/conf/bitbake.conf. 208 http://git.openembedded.org/bitbake/tree/conf/bitbake.conf.
174 209
175 Use the following commands to create the ``conf`` directory in the 210 Use the following commands to create the ``conf`` directory in the
176 project directory: $ mkdir conf From within the ``conf`` directory, 211 project directory: ::
212
213 $ mkdir conf
214
215 From within the ``conf`` directory,
177 use some editor to create the ``bitbake.conf`` so that it contains 216 use some editor to create the ``bitbake.conf`` so that it contains
178 the following: :term:`PN` = 217 the following: ::
179 "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] 218
180 or 'defaultpkgname'}" TMPDIR = "${:term:`TOPDIR`}/tmp" 219 PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
181 :term:`CACHE` = "${TMPDIR}/cache" 220
182 :term:`STAMP` = "${TMPDIR}/${PN}/stamps" 221 TMPDIR = "${TOPDIR}/tmp"
183 :term:`T` = "${TMPDIR}/${PN}/work" :term:`B` = 222 CACHE = "${TMPDIR}/cache"
184 "${TMPDIR}/${PN}" 223 STAMP = "${TMPDIR}/${PN}/stamps"
224 T = "${TMPDIR}/${PN}/work"
225 B = "${TMPDIR}/${PN}"
185 226
186 .. note:: 227 .. note::
187 228
188 Without a value for 229 Without a value for PN , the variables STAMP , T , and B , prevent more
189 PN 230 than one recipe from working. You can fix this by either setting PN to
190 , the variables 231 have a value similar to what OpenEmbedded and BitBake use in the default
191 STAMP 232 bitbake.conf file (see previous example). Or, by manually updating each
192 , 233 recipe to set PN . You will also need to include PN as part of the STAMP
193 T 234 , T , and B variable definitions in the local.conf file.
194 , and
195 B
196 , prevent more than one recipe from working. You can fix this by
197 either setting
198 PN
199 to have a value similar to what OpenEmbedded and BitBake use in
200 the default
201 bitbake.conf
202 file (see previous example). Or, by manually updating each recipe
203 to set
204 PN
205 . You will also need to include
206 PN
207 as part of the
208 STAMP
209 ,
210 T
211 , and
212 B
213 variable definitions in the
214 local.conf
215 file.
216 235
217 The ``TMPDIR`` variable establishes a directory that BitBake uses 236 The ``TMPDIR`` variable establishes a directory that BitBake uses
218 for build output and intermediate files other than the cached 237 for build output and intermediate files other than the cached
219 information used by the `Setscene <#setscene>`__ process. Here, the 238 information used by the
220 ``TMPDIR`` directory is set to ``hello/tmp``. 239 :ref:`bitbake-user-manual/bitbake-user-manual-execution:setscene`
240 process. Here, the ``TMPDIR`` directory is set to ``hello/tmp``.
221 241
222 .. note:: 242 .. tip::
223 243
224 You can always safely delete the 244 You can always safely delete the tmp directory in order to rebuild a
225 tmp 245 BitBake target. The build process creates the directory for you when you
226 directory in order to rebuild a BitBake target. The build process 246 run BitBake.
227 creates the directory for you when you run BitBake.
228 247
229 For information about each of the other variables defined in this 248 For information about each of the other variables defined in this
230 example, click on the links to take you to the definitions in the 249 example, check :term:`PN`, :term:`TOPDIR`, :term:`CACHE`, :term:`STAMP`,
250 :term:`T` or :term:`B` to take you to the definitions in the
231 glossary. 251 glossary.
232 252
2336. *Run BitBake:* After making sure that the ``conf/bitbake.conf`` file 253#. **Run BitBake:** After making sure that the ``conf/bitbake.conf`` file
234 exists, you can run the ``bitbake`` command again: $ bitbake ERROR: 254 exists, you can run the ``bitbake`` command again: ::
235 Traceback (most recent call last): File 255
236 "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in 256 $ bitbake
237 wrapped return func(fn, \*args) File 257 ERROR: Traceback (most recent call last):
238 "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in 258 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
239 \_inherit bb.parse.BBHandler.inherit(bbclass, "configuration 259 return func(fn, *args)
240 INHERITs", 0, data) File 260 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit
241 "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", 261 bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)
242 line 92, in inherit include(fn, file, lineno, d, "inherit") File 262 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit
243 "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", 263 include(fn, file, lineno, d, "inherit")
244 line 100, in include raise ParseError("Could not %(error_out)s file 264 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include
245 %(fn)s" % vars(), oldfn, lineno) ParseError: ParseError in 265 raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)
246 configuration INHERITs: Could not inherit file classes/base.bbclass 266 ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
247 ERROR: Unable to parse base: ParseError in configuration INHERITs: 267
248 Could not inherit file classes/base.bbclass In the sample output, 268 ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
269
270 In the sample output,
249 BitBake could not find the ``classes/base.bbclass`` file. You need 271 BitBake could not find the ``classes/base.bbclass`` file. You need
250 to create that file next. 272 to create that file next.
251 273
2527. *Creating ``classes/base.bbclass``:* BitBake uses class files to 274#. **Creating classes/base.bbclass:** BitBake uses class files to
253 provide common code and functionality. The minimally required class 275 provide common code and functionality. The minimally required class
254 for BitBake is the ``classes/base.bbclass`` file. The ``base`` class 276 for BitBake is the ``classes/base.bbclass`` file. The ``base`` class
255 is implicitly inherited by every recipe. BitBake looks for the class 277 is implicitly inherited by every recipe. BitBake looks for the class
256 in the ``classes`` directory of the project (i.e ``hello/classes`` 278 in the ``classes`` directory of the project (i.e ``hello/classes``
257 in this example). 279 in this example).
258 280
259 Create the ``classes`` directory as follows: $ cd $HOME/hello $ 281 Create the ``classes`` directory as follows: ::
260 mkdir classes Move to the ``classes`` directory and then create the 282
283 $ cd $HOME/hello
284 $ mkdir classes
285
286 Move to the ``classes`` directory and then create the
261 ``base.bbclass`` file by inserting this single line: addtask build 287 ``base.bbclass`` file by inserting this single line: addtask build
262 The minimal task that BitBake runs is the ``do_build`` task. This is 288 The minimal task that BitBake runs is the ``do_build`` task. This is
263 all the example needs in order to build the project. Of course, the 289 all the example needs in order to build the project. Of course, the
264 ``base.bbclass`` can have much more depending on which build 290 ``base.bbclass`` can have much more depending on which build
265 environments BitBake is supporting. 291 environments BitBake is supporting.
266 292
2678. *Run BitBake:* After making sure that the ``classes/base.bbclass`` 293#. **Run BitBake:** After making sure that the ``classes/base.bbclass``
268 file exists, you can run the ``bitbake`` command again: $ bitbake 294 file exists, you can run the ``bitbake`` command again: ::
269 Nothing to do. Use 'bitbake world' to build everything, or run 295
270 'bitbake --help' for usage information. BitBake is finally reporting 296 $ bitbake
297 Nothing to do. Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.
298
299 BitBake is finally reporting
271 no errors. However, you can see that it really does not have 300 no errors. However, you can see that it really does not have
272 anything to do. You need to create a recipe that gives BitBake 301 anything to do. You need to create a recipe that gives BitBake
273 something to do. 302 something to do.
274 303
2759. *Creating a Layer:* While it is not really necessary for such a 304#. **Creating a Layer:** While it is not really necessary for such a
276 small example, it is good practice to create a layer in which to 305 small example, it is good practice to create a layer in which to
277 keep your code separate from the general metadata used by BitBake. 306 keep your code separate from the general metadata used by BitBake.
278 Thus, this example creates and uses a layer called "mylayer". 307 Thus, this example creates and uses a layer called "mylayer".
@@ -285,78 +314,102 @@ Following is the complete "Hello World" example.
285 Minimally, you need a recipe file and a layer configuration file in 314 Minimally, you need a recipe file and a layer configuration file in
286 your layer. The configuration file needs to be in the ``conf`` 315 your layer. The configuration file needs to be in the ``conf``
287 directory inside the layer. Use these commands to set up the layer 316 directory inside the layer. Use these commands to set up the layer
288 and the ``conf`` directory: $ cd $HOME $ mkdir mylayer $ cd mylayer 317 and the ``conf`` directory: ::
289 $ mkdir conf Move to the ``conf`` directory and create a 318
290 ``layer.conf`` file that has the following: BBPATH .= 319 $ cd $HOME
291 ":${:term:`LAYERDIR`}" :term:`BBFILES` 320 $ mkdir mylayer
292 += "${LAYERDIR}/\*.bb" 321 $ cd mylayer
293 :term:`BBFILE_COLLECTIONS` += "mylayer" 322 $ mkdir conf
294 `BBFILE_PATTERN_mylayer <#var-bb-BBFILE_PATTERN>`__ := 323
295 "^${LAYERDIR_RE}/" For information on these variables, click the 324 Move to the ``conf`` directory and create a ``layer.conf`` file that has the
296 links to go to the definitions in the glossary. 325 following: ::
326
327 BBPATH .= ":${LAYERDIR}"
328 BBFILES += "${LAYERDIR}/\*.bb"
329 BBFILE_COLLECTIONS += "mylayer"
330 `BBFILE_PATTERN_mylayer := "^${LAYERDIR_RE}/"
331
332 For information on these variables, click on :term:`BBFILES`,
333 :term:`LAYERDIR`, :term:`BBFILE_COLLECTIONS` or :term:`BBFILE_PATTERN_mylayer <BBFILE_PATTERN>`
334 to go to the definitions in the glossary.
297 335
298 You need to create the recipe file next. Inside your layer at the 336 You need to create the recipe file next. Inside your layer at the
299 top-level, use an editor and create a recipe file named 337 top-level, use an editor and create a recipe file named
300 ``printhello.bb`` that has the following: 338 ``printhello.bb`` that has the following: ::
301 :term:`DESCRIPTION` = "Prints Hello World" 339
302 :term:`PN` = 'printhello' :term:`PV` = '1' python 340 DESCRIPTION = "Prints Hello World"
303 do_build() { bb.plain("********************"); bb.plain("\* \*"); 341 PN = 'printhello'
304 bb.plain("\* Hello, World! \*"); bb.plain("\* \*"); 342 PV = '1'
305 bb.plain("********************"); } The recipe file simply provides 343
344 python do_build() {
345 bb.plain("********************");
346 bb.plain("* *");
347 bb.plain("* Hello, World! *");
348 bb.plain("* *");
349 bb.plain("********************");
350 }
351
352 The recipe file simply provides
306 a description of the recipe, the name, version, and the ``do_build`` 353 a description of the recipe, the name, version, and the ``do_build``
307 task, which prints out "Hello World" to the console. For more 354 task, which prints out "Hello World" to the console. For more
308 information on these variables, follow the links to the glossary. 355 information on :term:`DESCRIPTION`, :term:`PN` or :term:`PV`
356 follow the links to the glossary.
357
358#. **Run BitBake With a Target:** Now that a BitBake target exists, run
359 the command and provide that target: ::
309 360
31010. *Run BitBake With a Target:* Now that a BitBake target exists, run 361 $ cd $HOME/hello
311 the command and provide that target: $ cd $HOME/hello $ bitbake 362 $ bitbake printhello
312 printhello ERROR: no recipe files to build, check your BBPATH and 363 ERROR: no recipe files to build, check your BBPATH and BBFILES?
313 BBFILES? Summary: There was 1 ERROR message shown, returning a 364
314 non-zero exit code. We have created the layer with the recipe and 365 Summary: There was 1 ERROR message shown, returning a non-zero exit code.
366
367 We have created the layer with the recipe and
315 the layer configuration file but it still seems that BitBake cannot 368 the layer configuration file but it still seems that BitBake cannot
316 find the recipe. BitBake needs a ``conf/bblayers.conf`` that lists 369 find the recipe. BitBake needs a ``conf/bblayers.conf`` that lists
317 the layers for the project. Without this file, BitBake cannot find 370 the layers for the project. Without this file, BitBake cannot find
318 the recipe. 371 the recipe.
319 372
32011. *Creating ``conf/bblayers.conf``:* BitBake uses the 373#. **Creating conf/bblayers.conf:** BitBake uses the
321 ``conf/bblayers.conf`` file to locate layers needed for the project. 374 ``conf/bblayers.conf`` file to locate layers needed for the project.
322 This file must reside in the ``conf`` directory of the project (i.e. 375 This file must reside in the ``conf`` directory of the project (i.e.
323 ``hello/conf`` for this example). 376 ``hello/conf`` for this example).
324 377
325 Set your working directory to the ``hello/conf`` directory and then 378 Set your working directory to the ``hello/conf`` directory and then
326 create the ``bblayers.conf`` file so that it contains the following: 379 create the ``bblayers.conf`` file so that it contains the following: ::
327 BBLAYERS ?= " \\ /home/<you>/mylayer \\ " You need to provide your 380
328 own information for ``you`` in the file. 381 BBLAYERS ?= " \
382 /home/<you>/mylayer \
383 "
384
385 You need to provide your own information for ``you`` in the file.
329 386
33012. *Run BitBake With a Target:* Now that you have supplied the 387#. **Run BitBake With a Target:** Now that you have supplied the
331 ``bblayers.conf`` file, run the ``bitbake`` command and provide the 388 ``bblayers.conf`` file, run the ``bitbake`` command and provide the
332 target: $ bitbake printhello Parsing recipes: 100% 389 target: ::
333 \|##################################################################################\| 390
334 Time: 00:00:00 Parsing of 1 .bb files complete (0 cached, 1 parsed). 391 $ bitbake printhello
335 1 targets, 0 skipped, 0 masked, 0 errors. NOTE: Resolving any 392 Parsing recipes: 100% |##################################################################################|
336 missing task queue dependencies NOTE: Preparing RunQueue NOTE: 393 Time: 00:00:00
337 Executing RunQueue Tasks \*******************\* \* \* \* Hello, 394 Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors.
338 World! \* \* \* \*******************\* NOTE: Tasks Summary: 395 NOTE: Resolving any missing task queue dependencies
339 Attempted 1 tasks of which 0 didn't need to be rerun and all 396 NOTE: Preparing RunQueue
340 succeeded. BitBake finds the ``printhello`` recipe and successfully 397 NOTE: Executing RunQueue Tasks
341 runs the task. 398 ********************
399 * *
400 * Hello, World! *
401 * *
402 ********************
403 NOTE: Tasks Summary: Attempted 1 tasks of which 0 didn't need to be rerun and all succeeded.
342 404
343 .. note:: 405 .. note::
344 406
345 After the first execution, re-running 407 After the first execution, re-running bitbake printhello again will not
346 bitbake printhello 408 result in a BitBake run that prints the same console output. The reason
347 again will not result in a BitBake run that prints the same 409 for this is that the first time the printhello.bb recipe's do_build task
348 console output. The reason for this is that the first time the 410 executes successfully, BitBake writes a stamp file for the task. Thus,
349 printhello.bb 411 the next time you attempt to run the task using that same bitbake
350 recipe's 412 command, BitBake notices the stamp and therefore determines that the task
351 do_build 413 does not need to be re-run. If you delete the tmp directory or run
352 task executes successfully, BitBake writes a stamp file for the 414 bitbake -c clean printhello and then re-run the build, the "Hello,
353 task. Thus, the next time you attempt to run the task using that 415 World!" message will be printed again.
354 same
355 bitbake
356 command, BitBake notices the stamp and therefore determines that
357 the task does not need to be re-run. If you delete the
358 tmp
359 directory or run
360 bitbake -c clean printhello
361 and then re-run the build, the "Hello, World!" message will be
362 printed again.