Blame - bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml - openbmc/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>

139

</para></listitem>

140

</itemizedlist>

</note>

<para>

As stated earlier, the goal of this example

145

is to eventually compile "Hello World".

146

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

147

to provide in order to achieve that goal.

148

Recall that BitBake utilizes three types of metadata files:

But where do they go?

153

How does BitBake find them?

154

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

155

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>

164

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

165

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

171

its work.

172

You can use this directory to keep all the metafiles needed

173

by BitBake.

174

Having a project directory is a good way to isolate your

175

project.

176

</para></listitem>

177

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

178

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

179

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

it does:

$ bitbake

The BBPATH variable is not set and bitbake did not

184

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

185

Maybe you accidentally invoked bitbake from the wrong directory?

186

DEBUG: Removed the following variables from the environment:

187

GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,

188

GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,

189

XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,

190

MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,

191

GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,

192

XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,

193

_, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH,

194

UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS

195

</literallayout>

196

The majority of this output is specific to environment variables

197

that are not directly relevant to BitBake.

198

However, the very first message regarding the

199

<filename>BBPATH</filename> variable and the

200

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

201

is relevant.</para>

202

<para>

203

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

204

The

205

206

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

207

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

208

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

209

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

210

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

211

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

212

file.

213

</para></listitem>

214

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

215

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

216

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

217

earlier in the appendix.

218

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

219

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

220

file for each project.</para>

221

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

222

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

223

224

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

225

$ export BBPATH

226

</literallayout>

227

Use your actual project directory in the command.

228

BitBake uses that directory to find the metadata it needs for

229

your project.

230

<note>

231

When specifying your project directory, do not use the

232

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

as the shell would.

</note>

</para></listitem>

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

237

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

238

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

239

240

$ bitbake

241

ERROR: Traceback (most recent call last):

242

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

243

return func(fn, *args)

244

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

245

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

246

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

247

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

248

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

249

abs_fn = resolve_file(fn, data)

250

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

251

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

252

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

253

254

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

255

</literallayout>

256

This sample output shows that BitBake could not find the

257

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

258

directory.

259

This file is the first thing BitBake must find in order

260

to build a target.

261

And, since the project directory for this example is

262

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

263

file.

264

</para></listitem>

265

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

266

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

267

configuration variables BitBake uses for metadata and recipe

268

files.

269

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

270

and define some key BitBake variables.

271

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

see

</para>

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

276

directory in the project directory:

$ mkdir conf

</literallayout>

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

281

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

282

so that it contains the following:

283

284

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

</literallayout>

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

291

that BitBake uses for build output and intermediate files (other

292

than the cached information used by the

293

294

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

295

<filename>hello/tmp</filename>.

296

297

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

298

directory in order to rebuild a BitBake target.

299

The build process creates the directory for you

300

when you run BitBake.

301

</note></para>

302

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

303

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

304

the glossary.

305

</para></listitem>

306

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

307

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

308

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

command again:

$ bitbake

ERROR: Traceback (most recent call last):

313

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

314

return func(fn, *args)

315

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

316

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

317

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

318

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

319

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

320

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

321

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

322

323

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

324

</literallayout>

325

In the sample output, BitBake could not find the

326

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

327

You need to create that file next.

328

</para></listitem>

329

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

330

BitBake uses class files to provide common code and functionality.

331

The minimally required class for BitBake is the

332

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

333

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

334

every recipe.

335

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

336

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

337

in this example).

338

</para>

339

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

$ cd $HOME/hello

$ mkdir classes

</literallayout>

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

345

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

this single line:

addtask build

</literallayout>

The minimal task that BitBake runs is the

351

<filename>do_build</filename> task.

352

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

353

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

354

more depending on which build environments BitBake is

355

supporting.

356

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

357

you can look at

358

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

359

</para></listitem>

360

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

361

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

362

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.

367

</literallayout>

368

BitBake is finally reporting no errors.

369

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

370

to do.

371

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

372

</para></listitem>

373

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

374

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

375

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

376

code separate from the general metadata used by BitBake.

377

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

378

<note>

379

You can find additional information on adding a layer at

380

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

381

</note>

382

</para>

383

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

384

file in your layer.

385

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

386

directory inside the layer.

387

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

396

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

397

398

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

</literallayout>

For information on these variables, click the links

406

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

407

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

408

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

409

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

has the following:

python do_build() {

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

418

bb.plain("* *");

419

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

420

bb.plain("* *");

421

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

422

}

423

</literallayout>

424

The recipe file simply provides a description of the

425

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

426

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

427

For more information on these variables, follow the links

428

to the glossary.

429

</para></listitem>

430

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

431

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?

437

438

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

439

</literallayout>

440

We have created the layer with the recipe and the layer

441

configuration file but it still seems that BitBake cannot

442

find the recipe.

443

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

444

lists the layers for the project.

445

Without this file, BitBake cannot find the recipe.

446

</para></listitem>

447

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

448

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

449

to locate layers needed for the project.

450

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

451

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

452

example).</para>

453

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

454

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

455

file so that it contains the following:

456

457

BBLAYERS ?= " \

458

/home/<you>/mylayer \

459

"

460

</literallayout>

461

You need to provide your own information for

462

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

463

</para></listitem>

464

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

465

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

466

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

the target:

$ bitbake printhello

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

471

Time: 00:00:00

472

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

473

NOTE: Resolving any missing task queue dependencies

474

NOTE: Preparing RunQueue

475

NOTE: Executing RunQueue Tasks

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

* *

* Hello, World! *

* *

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

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

482

</literallayout>

483

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

484

successfully runs the task.

485

<note>

486

After the first execution, re-running

487

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

488

result in a BitBake run that prints the same console

489

output.

490

The reason for this is that the first time the

491

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

492

<filename>do_build</filename> task executes

493

successfully, BitBake writes a stamp file for the task.

494

Thus, the next time you attempt to run the task

495

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

496

BitBake notices the stamp and therefore determines

497

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

498

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

499

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

500

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

be printed again.

</note>

</para></listitem>

</orderedlist>

</section>

</appendix>