Blame - import-layers/yocto-poky/documentation/ref-manual/ref-features.xml - openbmc/openbmc

Patrick Williams

c124f4f

2015-09-15 14:41:29 -0500

[diff] [blame]

1

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

2

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

3

[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

4

5

6

<title>Features</title>

7

8

<para>

9

This chapter provides a reference of shipped machine and distro features

10

you can include as part of your image, a reference on image features you can

11

select, and a reference on feature backfilling.

</para>

<para>

Features provide a mechanism for working out which packages

16

should be included in the generated images.

17

Distributions can select which features they want to support through the

18

<filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>

19

variable, which is set or appended to in a distribution's configuration file such as

20

<filename>poky.conf</filename>,

21

<filename>poky-tiny.conf</filename>,

22

<filename>poky-lsb.conf</filename> and so forth.

23

Machine features are set in the

24

<filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>

25

variable, which is set in the machine configuration file and

26

specifies the hardware features for a given machine.

</para>

<para>

These two variables combine to work out which kernel modules,

31

utilities, and other packages to include.

32

A given distribution can support a selected subset of features so some machine features might not

33

be included if the distribution itself does not support them.

</para>

<para>

One method you can use to determine which recipes are checking to see if a

38

particular feature is contained or not is to <filename>grep</filename> through

39

the <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>

40

for the feature.

41

Here is an example that discovers the recipes whose build is potentially

42

changed based on a given feature:

43

44

$ cd poky

45

$ git grep 'contains.*MACHINE_FEATURES.*<replaceable>feature</replaceable>'

</literallayout>

</para>

<title>Machine Features</title>

51

52

<para>

53

The items below are features you can use with

54

55

Features do not have a one-to-one correspondence to packages, and they can

56

go beyond simply controlling the installation of a package or packages.

57

Sometimes a feature can influence how certain recipes are built.

58

For example, a feature might determine whether a particular configure option

59

is specified within the

60

61

task for a particular recipe.

</para>

<para>

This feature list only represents features as shipped with the Yocto Project metadata:

66

67

<listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only)

68

</para></listitem>

69

<listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers

70

</para></listitem>

71

<listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation)

72

</para></listitem>

73

<listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT

74

</para></listitem>

75

<listitem><para><emphasis>efi:</emphasis> Support for booting through EFI

76

</para></listitem>

77

<listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive

78

</para></listitem>

79

<listitem><para><emphasis>irda:</emphasis> Hardware has IrDA support

80

</para></listitem>

81

<listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard

82

</para></listitem>

83

<listitem><para><emphasis>pcbios:</emphasis> Support for booting through BIOS

84

</para></listitem>

85

<listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus

86

</para></listitem>

87

<listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets

88

</para></listitem>

89

<listitem><para><emphasis>phone:</emphasis> Mobile phone (voice) support

90

</para></listitem>

91

<listitem><para><emphasis>qvga:</emphasis> Machine has a QVGA (320x240) display

92

</para></listitem>

93

<listitem><para><emphasis>rtc:</emphasis> Machine has a Real-Time Clock

94

</para></listitem>

95

<listitem><para><emphasis>screen:</emphasis> Hardware has a screen

96

</para></listitem>

97

<listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232)

98

</para></listitem>

99

<listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen

100

</para></listitem>

101

<listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable

102

</para></listitem>

103

<listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable

104

</para></listitem>

105

<listitem><para><emphasis>vfat:</emphasis> FAT file system support

106

</para></listitem>

107

<listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Distro Features</title>

115

116

<para>

117

The items below are features you can use with

118

119

to enable features across your distribution.

120

Features do not have a one-to-one correspondence to packages,

121

and they can go beyond simply controlling the installation of a

122

package or packages.

123

In most cases, the presence or absence of a feature translates to

124

the appropriate option supplied to the configure script during the

125

126

task for the recipes that optionally

support the feature.

</para>

<para>

Some distro features are also machine features.

132

These select features make sense to be controlled both at

133

the machine and distribution configuration level.

134

See the

135

<ulink url='&YOCTO_DOCS_REF_URL;#var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></ulink>

136

variable for more information.

</para>

<para>

This list only represents features as shipped with the Yocto Project metadata:

141

142

<listitem><para><emphasis>alsa:</emphasis> Include ALSA support

143

(OSS compatibility kernel modules installed if available).

144

</para></listitem>

Brad Bishop

37a0e4d

2017-12-04 01:01:44 -0500

[diff] [blame^]

145

<listitem><para><emphasis>api-documentation:</emphasis>

146

Enables generation of API documentation during recipe

147

builds.

148

The resulting documentation is added to SDK tarballs

149

when the

150

<filename>bitbake -c populate_sdk</filename> command

151

is used.

152

See the

153

"<ulink url='&YOCTO_DOCS_SDK_URL;#adding-api-documentation-to-the-standard-sdk'>Adding API Documentation to the Standard SDK</ulink>"

154

section in the Yocto Project Software Development Kit (SDK)

155

Developer's Guide for more information.

156

</para></listitem>

Patrick Williams

c124f4f

2015-09-15 14:41:29 -0500

[diff] [blame]

157

<listitem><para><emphasis>bluetooth:</emphasis> Include

158

bluetooth support (integrated BT only).</para></listitem>

Patrick Williams

c0f7c04

2017-02-23 20:41:17 -0600

[diff] [blame]

159

<listitem><para><emphasis>bluez5:</emphasis> Include

160

BlueZ Version 5, which provides core Bluetooth layers and

161

protocols support.

162

<note>

163

The default value for the

164

165

variable includes "bluetooth", which causes bluez5

166

to be backfilled in for bluetooth support.

167

If you do not want bluez5 backfilled and would rather

168

use bluez4, you need to use the

variable as follows:

DISTRO_FEATURES_BACKFILL_CONSIDERED = "bluez5"

173

</literallayout>

174

Setting this variable tells the OpenEmbedded build

175

system that you have considered but ruled

176

out using the bluez5 feature and that bluez4 will be

177

used.

178

</note>

179

</para></listitem>

Patrick Williams

c124f4f

2015-09-15 14:41:29 -0500

[diff] [blame]

180

<listitem><para><emphasis>cramfs:</emphasis> Include CramFS

181

support.</para></listitem>

182

<listitem><para><emphasis>directfb:</emphasis>

183

Include DirectFB support.

184

</para></listitem>

185

<listitem><para><emphasis>ext2:</emphasis> Include tools for

186

supporting for devices with internal HDD/Microdrive for

187

storing files (instead of Flash only devices).

188

</para></listitem>

189

<listitem><para><emphasis>ipsec:</emphasis> Include IPSec

190

support.</para></listitem>

191

<listitem><para><emphasis>ipv6:</emphasis> Include IPv6 support.

192

</para></listitem>

193

<listitem><para><emphasis>irda:</emphasis> Include IrDA support.

194

</para></listitem>

195

<listitem><para><emphasis>keyboard:</emphasis> Include keyboard

196

support (e.g. keymaps will be loaded during boot).

197

</para></listitem>

198

<listitem><para><emphasis>nfs:</emphasis> Include NFS client

199

support (for mounting NFS exports on device).

200

</para></listitem>

201

<listitem><para><emphasis>opengl:</emphasis>

202

Include the Open Graphics Library, which is a

203

cross-language, multi-platform application programming

204

interface used for rendering two and three-dimensional

205

graphics.</para></listitem>

206

<listitem><para><emphasis>pci:</emphasis> Include PCI bus

207

support.</para></listitem>

208

<listitem><para><emphasis>pcmcia:</emphasis> Include

209

PCMCIA/CompactFlash support.</para></listitem>

210

<listitem><para><emphasis>ppp:</emphasis> Include PPP dialup

211

support.</para></listitem>

212

<listitem><para><emphasis>ptest:</emphasis> Enables building

213

the package tests where supported by individual recipes.

214

For more information on package tests, see the

215

"<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"

216

section in the Yocto Project Development Manual.

217

</para></listitem>

218

<listitem><para><emphasis>smbfs:</emphasis> Include SMB networks

219

client support (for mounting Samba/Microsoft Windows shares

220

on device).</para></listitem>

221

<listitem><para><emphasis>systemd:</emphasis> Include support

222

for this <filename>init</filename> manager, which is a full

223

replacement of for <filename>init</filename> with parallel

224

starting of services, reduced shell overhead, and other

225

features.

226

This <filename>init</filename> manager is used by many

227

distributions.</para></listitem>

228

<listitem><para><emphasis>usbgadget:</emphasis> Include USB

229

Gadget Device support (for USB networking/serial/storage).

230

</para></listitem>

231

<listitem><para><emphasis>usbhost:</emphasis> Include USB Host

232

support (allows to connect external keyboard, mouse,

233

storage, network etc).</para></listitem>

234

<listitem><para><emphasis>wayland:</emphasis> Include the

235

Wayland display server protocol and the library that

236

supports it.</para></listitem>

237

<listitem><para><emphasis>wifi:</emphasis> Include WiFi support

238

(integrated only).</para></listitem>

239

<listitem><para><emphasis>x11:</emphasis> Include the X server

240

and libraries.</para></listitem>

</itemizedlist>

</para>

</section>

<title>Image Features</title>

247

248

<para>

249

The contents of images generated by the OpenEmbedded build system

250

can be controlled by the

and

variables that you typically configure in your image recipes.

255

Through these variables, you can add several different

256

predefined packages such as development utilities or packages with

257

debug information needed to investigate application problems or

258

profile applications.

</para>

<para>

The following image features are available for all images:

263

264

<listitem><para><emphasis>allow-empty-password:</emphasis>

265

Allows Dropbear and OpenSSH to accept root logins

266

and logins from accounts having an empty password string.

267

</para></listitem>

268

269

Installs debug symbol packages for all packages installed

270

in a given image.

271

</para></listitem>

272

<listitem><para><emphasis>debug-tweaks:</emphasis>

273

Makes an image suitable for development (e.g.

274

allows root logins without passwords and enables

275

post-installation logging).

276

See the 'allow-empty-password', 'empty-root-password',

277

and 'post-install-logging' features in this list for

278

additional information.

279

</para></listitem>

280

281

Installs development packages (headers and extra library

282

links) for all packages installed in a given image.

283

</para></listitem>

284

<listitem><para><emphasis>doc-pkgs:</emphasis> Installs

285

documentation packages for all packages installed in a

286

given image.

287

</para></listitem>

288

<listitem><para><emphasis>empty-root-password:</emphasis>

289

Sets the root password to an empty string, which allows

290

logins with a blank password.

291

</para></listitem>

292

<listitem><para><emphasis>package-management:</emphasis>

293

Installs package management tools and preserves the package

294

manager database.

295

</para></listitem>

296

<listitem><para><emphasis>post-install-logging:</emphasis>

297

Enables logging postinstall script runs to

298

the <filename>/var/log/postinstall.log</filename> file

299

on first boot of the image on the target system.

300

</para></listitem>

301

<listitem><para><emphasis>ptest-pkgs:</emphasis>

302

Installs ptest packages for all ptest-enabled recipes.

303

</para></listitem>

304

<listitem><para><emphasis>read-only-rootfs:</emphasis>

305

Creates an image whose root filesystem is read-only.

306

See the

307

"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"

308

section in the Yocto Project Development Manual for more

309

information.

310

</para></listitem>

311

<listitem><para><emphasis>splash:</emphasis>

312

Enables showing a splash screen during boot.

313

By default, this screen is provided by

314

<filename>psplash</filename>, which does allow

315

customization.

316

If you prefer to use an alternative splash screen package,

317

you can do so by setting the <filename>SPLASH</filename>

318

variable to a different package name (or names) within the

319

image recipe or at the distro configuration level.

320

</para></listitem>

321

<listitem><para><emphasis>staticdev-pkgs:</emphasis>

322

Installs static development packages, which are

323

static libraries (i.e. <filename>*.a</filename> files), for

324

all packages installed in a given image.

</para></listitem>

</itemizedlist>

</para>

<para>

Some image features are available only when you inherit the

331

332

class.

333

The current list of these valid features is as follows:

334

335

<listitem><para><emphasis>eclipse-debug:</emphasis> Provides

336

Eclipse remote debugging support.

337

</para></listitem>

338

<listitem><para><emphasis>hwcodecs:</emphasis> Installs

339

hardware acceleration codecs.

340

</para></listitem>

341

<listitem><para><emphasis>nfs-server:</emphasis>

342

Installs an NFS server.

343

</para></listitem>

Patrick Williams

d8c66bc

2016-06-20 12:57:21 -0500

[diff] [blame]

344

345

Installs profiling tools such as

346

<filename>perf</filename>, <filename>systemtap</filename>,

347

and <filename>LTTng</filename>.

348

For general information on user-space tools, see the

349

<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.

Patrick Williams

c124f4f

2015-09-15 14:41:29 -0500

[diff] [blame]

350

</para></listitem>

351

<listitem><para><emphasis>ssh-server-dropbear:</emphasis>

352

Installs the Dropbear minimal SSH server.

353

</para></listitem>

354

<listitem><para><emphasis>ssh-server-openssh:</emphasis>

355

Installs the OpenSSH SSH server, which is more

356

full-featured than Dropbear.

357

Note that if both the OpenSSH SSH server and the Dropbear

358

minimal SSH server are present in

359

<filename>IMAGE_FEATURES</filename>, then OpenSSH will take

360

precedence and Dropbear will not be installed.

361

</para></listitem>

362

<listitem><para><emphasis>tools-debug:</emphasis>

363

Installs debugging tools such as

364

<filename>strace</filename> and <filename>gdb</filename>.

365

For information on GDB, see the

366

"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"

367

section in the Yocto Project Development Manual.

368

For information on tracing and profiling, see the

369

<ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.

370

</para></listitem>

Patrick Williams

c124f4f

2015-09-15 14:41:29 -0500

[diff] [blame]

371

<listitem><para><emphasis>tools-sdk:</emphasis>

372

Installs a full SDK that runs on the device.

373

</para></listitem>

374

<listitem><para><emphasis>tools-testapps:</emphasis>

375

Installs device testing tools (e.g. touchscreen debugging).

376

</para></listitem>

377

378

Installs the X server.

379

</para></listitem>

380

381

Installs the X server with a minimal environment.

382

</para></listitem>

383

384

Installs the OpenedHand Sato environment.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Feature Backfilling</title>

393

394

<para>

395

Sometimes it is necessary in the OpenEmbedded build system to extend

396

397

or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>

398

to control functionality that was previously enabled and not able

399

to be disabled.

400

For these cases, we need to add an

401

additional feature item to appear in one of these variables,

402

but we do not want to force developers who have existing values

403

of the variables in their configuration to add the new feature

404

in order to retain the same overall level of functionality.

405

Thus, the OpenEmbedded build system has a mechanism to

406

automatically "backfill" these added features into existing

407

distro or machine configurations.

408

You can see the list of features for which this is done by

409

finding the

410

411

and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>

412

variables in the <filename>meta/conf/bitbake.conf</filename> file.

</para>

<para>

Because such features are backfilled by default into all

417

configurations as described in the previous paragraph, developers

418

who wish to disable the new features need to be able to selectively

419

prevent the backfilling from occurring.

420

They can do this by adding the undesired feature or features to the

421

422

or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>

423

variables for distro features and machine features respectively.

</para>

<para>

Here are two examples to help illustrate feature backfilling:

428

429

<listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:

430

Previously, PulseAudio support was enabled within the Qt and

431

GStreamer frameworks.

432

Because of this, the feature is backfilled and thus

433

enabled for all distros through the

434

<filename>DISTRO_FEATURES_BACKFILL</filename>

435

variable in the <filename>meta/conf/bitbake.conf</filename> file.

436

However, your distro needs to disable the feature.

437

You can disable the feature without affecting

438

other existing distro configurations that need PulseAudio support

439

by adding "pulseaudio" to

440

<filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>

441

in your distro's <filename>.conf</filename> file.

442

Adding the feature to this variable when it also

443

exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>

444

variable prevents the build system from adding the feature to

445

your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling

446

the feature for that particular distro.</para></listitem>

447

<listitem><para><emphasis>The "rtc" machine feature option</emphasis>:

448

Previously, real time clock (RTC) support was enabled for all

449

target devices.

450

Because of this, the feature is backfilled and thus enabled

451

for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>

452

variable in the <filename>meta/conf/bitbake.conf</filename> file.

453

However, your target device does not have this capability.

454

You can disable RTC support for your device without

455

affecting other machines that need RTC support

456

by adding the feature to your machine's

457

<filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>

458

list in the machine's <filename>.conf</filename> file.

459

Adding the feature to this variable when it also

460

exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>

461

variable prevents the build system from adding the feature to

462

your configuration's <filename>MACHINE_FEATURES</filename>, effectively

463

disabling RTC support for that particular machine.</para></listitem>

</itemizedlist>

</para>

</section>

</chapter>

<!--

vim: expandtab tw=80 ts=4 spell spelllang=en_gb

471

-->