Blame - yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml - stefanberger/openbmc

<ulink url="http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/">Hambedded Linux blog post - From Bitbake Hello World to an Image</ulink>

138

</para></listitem>

139

</itemizedlist>

</note>

<para>

As stated earlier, the goal of this example

144

is to eventually compile "Hello World".

145

However, it is unknown what BitBake needs and what you have

146

to provide in order to achieve that goal.

147

Recall that BitBake utilizes three types of metadata files:

But where do they go?

152

How does BitBake find them?

153

BitBake's error messaging helps you answer these types of questions

154

and helps you better understand exactly what is going on.

</para>

<para>

Following is the complete "Hello World" example.

</para>

<listitem><para><emphasis>Create a Project Directory:</emphasis>

163

First, set up a directory for the "Hello World" project.

164

Here is how you can do so in your home directory:

$ mkdir ~/hello

$ cd ~/hello

</literallayout>

This is the directory that BitBake will use to do all of

170

its work.

171

You can use this directory to keep all the metafiles needed

172

by BitBake.

173

Having a project directory is a good way to isolate your

174

project.

175

</para></listitem>

176

<listitem><para><emphasis>Run Bitbake:</emphasis>

177

At this point, you have nothing but a project directory.

178

Run the <filename>bitbake</filename> command and see what

it does:

$ bitbake

The BBPATH variable is not set and bitbake did not

183

find a conf/bblayers.conf file in the expected location.

184

Maybe you accidentally invoked bitbake from the wrong directory?

185

DEBUG: Removed the following variables from the environment:

186

GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,

187

GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,

188

XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,

189

MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,

190

GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,

191

XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,

192

_, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH,

193

UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS

194

</literallayout>

195

The majority of this output is specific to environment variables

196

that are not directly relevant to BitBake.

197

However, the very first message regarding the

198

<filename>BBPATH</filename> variable and the

199

<filename>conf/bblayers.conf</filename> file

200

is relevant.</para>

201

<para>

202

When you run BitBake, it begins looking for metadata files.

203

The

204

205

variable is what tells BitBake where to look for those files.

206

<filename>BBPATH</filename> is not set and you need to set it.

207

Without <filename>BBPATH</filename>, Bitbake cannot

208

find any configuration files (<filename>.conf</filename>)

209

or recipe files (<filename>.bb</filename>) at all.

210

BitBake also cannot find the <filename>bitbake.conf</filename>

211

file.

212

</para></listitem>

213

<listitem><para><emphasis>Setting <filename>BBPATH</filename>:</emphasis>

214

For this example, you can set <filename>BBPATH</filename>

215

in the same manner that you set <filename>PATH</filename>

216

earlier in the appendix.

217

You should realize, though, that it is much more flexible to set the

218

<filename>BBPATH</filename> variable up in a configuration

219

file for each project.</para>

220

<para>From your shell, enter the following commands to set and

221

export the <filename>BBPATH</filename> variable:

222

223

$ BBPATH="<replaceable>projectdirectory</replaceable>"

224

$ export BBPATH

225

</literallayout>

226

Use your actual project directory in the command.

227

BitBake uses that directory to find the metadata it needs for

228

your project.

229

<note>

230

When specifying your project directory, do not use the

231

tilde ("~") character as BitBake does not expand that character

as the shell would.

</note>

</para></listitem>

<listitem><para><emphasis>Run Bitbake:</emphasis>

236

Now that you have <filename>BBPATH</filename> defined, run

237

the <filename>bitbake</filename> command again:

238

239

$ bitbake

240

ERROR: Traceback (most recent call last):

241

File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped

242

return func(fn, *args)

243

File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file

244

return bb.parse.handle(fn, data, include)

245

File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle

246

return h['handle'](fn, data, include)

247

File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle

248

abs_fn = resolve_file(fn, data)

249

File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file

250

raise IOError("file %s not found in %s" % (fn, bbpath))

251

IOError: file conf/bitbake.conf not found in /home/scott-lenovo/hello

252

253

ERROR: Unable to parse conf/bitbake.conf: file conf/bitbake.conf not found in /home/scott-lenovo/hello

254

</literallayout>

255

This sample output shows that BitBake could not find the

256

<filename>conf/bitbake.conf</filename> file in the project

257

directory.

258

This file is the first thing BitBake must find in order

259

to build a target.

260

And, since the project directory for this example is

261

empty, you need to provide a <filename>conf/bitbake.conf</filename>

262

file.

263

</para></listitem>

264

<listitem><para><emphasis>Creating <filename>conf/bitbake.conf</filename>:</emphasis>

265

The <filename>conf/bitbake.conf</filename> includes a number of

266

configuration variables BitBake uses for metadata and recipe

267

files.

268

For this example, you need to create the file in your project directory

269

and define some key BitBake variables.

270

For more information on the <filename>bitbake.conf</filename>,

see

</para>

<para>Use the following commands to create the <filename>conf</filename>

275

directory in the project directory:

$ mkdir conf

</literallayout>

From within the <filename>conf</filename> directory, use

280

some editor to create the <filename>bitbake.conf</filename>

281

so that it contains the following:

282

283

TMPDIR = "${<link linkend='var-TOPDIR'>TOPDIR</link>}/tmp"

</literallayout>

The <filename>TMPDIR</filename> variable establishes a directory

290

that BitBake uses for build output and intermediate files (other

291

than the cached information used by the

292

293

Here, the <filename>TMPDIR</filename> directory is set to

294

<filename>hello/tmp</filename>.

295

296

You can always safely delete the <filename>tmp</filename>

297

directory in order to rebuild a BitBake target.

298

The build process creates the directory for you

299

when you run BitBake.

300

</note></para>

301

<para>For information about each of the other variables defined in this

302

example, click on the links to take you to the definitions in

303

the glossary.

304

</para></listitem>

305

<listitem><para><emphasis>Run Bitbake:</emphasis>

306

After making sure that the <filename>conf/bitbake.conf</filename>

307

file exists, you can run the <filename>bitbake</filename>

command again:

$ bitbake

ERROR: Traceback (most recent call last):

312

File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped

313

return func(fn, *args)

314

File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit

315

bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)

316

File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit

317

include(fn, file, lineno, d, "inherit")

318

File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include

319

raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)

320

ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass

321

322

ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass

323

</literallayout>

324

In the sample output, BitBake could not find the

325

<filename>classes/base.bbclass</filename> file.

326

You need to create that file next.

327

</para></listitem>

328

<listitem><para><emphasis>Creating <filename>classes/base.bbclass</filename>:</emphasis>

329

BitBake uses class files to provide common code and functionality.

330

The minimally required class for BitBake is the

331

<filename>classes/base.bbclass</filename> file.

332

The <filename>base</filename> class is implicitly inherited by

333

every recipe.

334

BitBake looks for the class in the <filename>classes</filename>

335

directory of the project (i.e <filename>hello/classes</filename>

336

in this example).

337

</para>

338

<para>Create the <filename>classes</filename> directory as follows:

$ cd $HOME/hello

$ mkdir classes

</literallayout>

Move to the <filename>classes</filename> directory and then

344

create the <filename>base.bbclass</filename> file by inserting

this single line:

addtask build

</literallayout>

The minimal task that BitBake runs is the

350

<filename>do_build</filename> task.

351

This is all the example needs in order to build the project.

352

Of course, the <filename>base.bbclass</filename> can have much

353

more depending on which build environments BitBake is

354

supporting.

355

For more information on the <filename>base.bbclass</filename> file,

356

you can look at

357

<ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#tasks'></ulink>.

358

</para></listitem>

359

<listitem><para><emphasis>Run Bitbake:</emphasis>

360

After making sure that the <filename>classes/base.bbclass</filename>

361

file exists, you can run the <filename>bitbake</filename>

command again:

$ bitbake

Nothing to do. Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.

366

</literallayout>

367

BitBake is finally reporting no errors.

368

However, you can see that it really does not have anything

369

to do.

370

You need to create a recipe that gives BitBake something to do.

371

</para></listitem>

372

<listitem><para><emphasis>Creating a Layer:</emphasis>

373

While it is not really necessary for such a small example,

374

it is good practice to create a layer in which to keep your

375

code separate from the general metadata used by BitBake.

376

Thus, this example creates and uses a layer called "mylayer".

377

<note>

378

You can find additional information on adding a layer at

379

<ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#adding-an-example-layer'></ulink>.

380

</note>

381

</para>

382

<para>Minimally, you need a recipe file and a layer configuration

383

file in your layer.

384

The configuration file needs to be in the <filename>conf</filename>

385

directory inside the layer.

386

Use these commands to set up the layer and the <filename>conf</filename>

directory:

$ cd $HOME

$ mkdir mylayer

$ cd mylayer

$ mkdir conf

</literallayout>

Move to the <filename>conf</filename> directory and create a

395

<filename>layer.conf</filename> file that has the following:

396

397

BBPATH .= ":${<link linkend='var-LAYERDIR'>LAYERDIR</link>}"

</literallayout>

For information on these variables, click the links

405

to go to the definitions in the glossary.</para>

406

<para>You need to create the recipe file next.

407

Inside your layer at the top-level, use an editor and create

408

a recipe file named <filename>printhello.bb</filename> that

has the following:

python do_build() {

bb.plain("********************");

417

bb.plain("* *");

418

bb.plain("* Hello, World! *");

419

bb.plain("* *");

420

bb.plain("********************");

421

}

422

</literallayout>

423

The recipe file simply provides a description of the

424

recipe, the name, version, and the <filename>do_build</filename>

425

task, which prints out "Hello World" to the console.

426

For more information on these variables, follow the links

427

to the glossary.

428

</para></listitem>

429

<listitem><para><emphasis>Run Bitbake With a Target:</emphasis>

430

Now that a BitBake target exists, run the command and provide

that target:

$ cd $HOME/hello

$ bitbake printhello

ERROR: no recipe files to build, check your BBPATH and BBFILES?

436

437

Summary: There was 1 ERROR message shown, returning a non-zero exit code.

438

</literallayout>

439

We have created the layer with the recipe and the layer

440

configuration file but it still seems that BitBake cannot

441

find the recipe.

442

BitBake needs a <filename>conf/bblayers.conf</filename> that

443

lists the layers for the project.

444

Without this file, BitBake cannot find the recipe.

445

</para></listitem>

446

<listitem><para><emphasis>Creating <filename>conf/bblayers.conf</filename>:</emphasis>

447

BitBake uses the <filename>conf/bblayers.conf</filename> file

448

to locate layers needed for the project.

449

This file must reside in the <filename>conf</filename> directory

450

of the project (i.e. <filename>hello/conf</filename> for this

451

example).</para>

452

<para>Set your working directory to the <filename>hello/conf</filename>

453

directory and then create the <filename>bblayers.conf</filename>

454

file so that it contains the following:

455

456

BBLAYERS ?= " \

457

/home/<you>/mylayer \

458

"

459

</literallayout>

460

You need to provide your own information for

461

<filename>you</filename> in the file.

462

</para></listitem>

463

<listitem><para><emphasis>Run Bitbake With a Target:</emphasis>

464

Now that you have supplied the <filename>bblayers.conf</filename>

465

file, run the <filename>bitbake</filename> command and provide

the target:

$ bitbake printhello

Parsing recipes: 100% |##################################################################################|

470

Time: 00:00:00

471

Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors.

472

NOTE: Resolving any missing task queue dependencies

473

NOTE: Preparing RunQueue

474

NOTE: Executing RunQueue Tasks

********************

* *

* Hello, World! *

* *

********************

NOTE: Tasks Summary: Attempted 1 tasks of which 0 didn't need to be rerun and all succeeded.

481

</literallayout>

482

BitBake finds the <filename>printhello</filename> recipe and

483

successfully runs the task.

484

<note>

485

After the first execution, re-running

486

<filename>bitbake printhello</filename> again will not

487

result in a BitBake run that prints the same console

488

output.

489

The reason for this is that the first time the

490

<filename>printhello.bb</filename> recipe's

491

<filename>do_build</filename> task executes

492

successfully, BitBake writes a stamp file for the task.

493

Thus, the next time you attempt to run the task

494

using that same <filename>bitbake</filename> command,

495

BitBake notices the stamp and therefore determines

496

that the task does not need to be re-run.

497

If you delete the <filename>tmp</filename> directory

498

or run <filename>bitbake -c clean printhello</filename>

499

and then re-run the build, the "Hello, World!" message will

be printed again.

</note>

</para></listitem>

</orderedlist>

</section>

</appendix>