Blame - poky/documentation/ref-manual/ref-features.xml - mdmillerii/openbmc

Andrew Geissler

4873add

2020-11-02 18:44:49 -0600

[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

7

<title>Features</title>

8

9

<para>

10

This chapter provides a reference of shipped machine and distro features

11

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

12

select, and a reference on feature backfilling.

</para>

<para>

Features provide a mechanism for working out which packages

17

should be included in the generated images.

18

Distributions can select which features they want to support through the

19

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

20

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

21

<filename>poky.conf</filename>,

22

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

23

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

24

Machine features are set in the

25

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

26

variable, which is set in the machine configuration file and

27

specifies the hardware features for a given machine.

</para>

<para>

These two variables combine to work out which kernel modules,

32

utilities, and other packages to include.

33

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

34

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

39

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

40

the <link linkend='metadata'>Metadata</link>

41

for the feature.

42

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

43

changed based on a given feature:

44

45

$ cd poky

46

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

</literallayout>

</para>

<title>Machine Features</title>

52

53

<para>

54

The items below are features you can use with

55

56

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

57

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

58

Sometimes a feature can influence how certain recipes are built.

59

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

60

is specified within the

61

62

task for a particular recipe.

</para>

<para>

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

67

68

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

69

</para></listitem>

70

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

71

</para></listitem>

72

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

73

</para></listitem>

74

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

75

</para></listitem>

76

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

77

</para></listitem>

78

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

79

</para></listitem>

80

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

81

</para></listitem>

82

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

83

</para></listitem>

84

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

85

</para></listitem>

86

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

87

</para></listitem>

88

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

89

</para></listitem>

90

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

91

</para></listitem>

92

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

93

</para></listitem>

94

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

95

</para></listitem>

96

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

97

</para></listitem>

98

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

99

</para></listitem>

100

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

101

</para></listitem>

102

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

103

</para></listitem>

104

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

105

</para></listitem>

106

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

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Distro Features</title>

114

115

<para>

116

The items below are features you can use with

117

118

to enable features across your distribution.

119

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

120

and they can go beyond simply controlling the installation of a

121

package or packages.

122

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

123

the appropriate option supplied to the configure script during the

124

125

task for the recipes that optionally

support the feature.

</para>

<para>

Some distro features are also machine features.

131

These select features make sense to be controlled both at

132

the machine and distribution configuration level.

133

See the

134

135

variable for more information.

</para>

<para>

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

140

141

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

142

(OSS compatibility kernel modules installed if available).

143

</para></listitem>

144

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

145

Enables generation of API documentation during recipe

146

builds.

147

The resulting documentation is added to SDK tarballs

148

when the

149

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

150

is used.

151

See the

152

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

153

section in the Yocto Project Application Development and

154

the Extensible Software Development Kit (eSDK) manual.

155

</para></listitem>

156

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

157

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

158

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

159

support.</para></listitem>

160

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

161

Include DirectFB support.

162

</para></listitem>

163

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

164

supporting for devices with internal HDD/Microdrive for

165

storing files (instead of Flash only devices).

166

</para></listitem>

167

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

168

support.</para></listitem>

169

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

170

</para></listitem>

171

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

172

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

173

</para></listitem>

174

<listitem><para><emphasis>ldconfig:</emphasis>

175

Include support for ldconfig and

176

<filename>ld.so.conf</filename> on the target.

177

</para></listitem>

178

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

179

support (for mounting NFS exports on device).

180

</para></listitem>

181

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

182

Include the Open Graphics Library, which is a

183

cross-language, multi-platform application programming

184

interface used for rendering two and three-dimensional

185

graphics.</para></listitem>

186

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

187

support.</para></listitem>

188

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

189

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

190

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

191

support.</para></listitem>

192

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

193

the package tests where supported by individual recipes.

194

For more information on package tests, see the

195

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

196

section in the Yocto Project Development Tasks Manual.

197

</para></listitem>

198

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

199

client support (for mounting Samba/Microsoft Windows shares

200

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

201

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

202

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

203

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

204

starting of services, reduced shell overhead, and other

205

features.

206

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

207

distributions.</para></listitem>

208

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

209

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

210

</para></listitem>

211

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

212

support (allows to connect external keyboard, mouse,

213

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

214

<listitem><para><emphasis>usrmerge:</emphasis> Merges the

215

<filename>/bin</filename>, <filename>/sbin</filename>,

216

217

directories into their respective counterparts in the

218

<filename>/usr</filename> directory to provide better package

219

and application compatibility.</para></listitem>

220

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

221

Wayland display server protocol and the library that

222

supports it.</para></listitem>

223

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

224

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

225

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

226

and libraries.</para></listitem>

</itemizedlist>

</para>

</section>

<title>Image Features</title>

233

234

<para>

235

The contents of images generated by the OpenEmbedded build system

236

can be controlled by the

and

variables that you typically configure in your image recipes.

241

Through these variables, you can add several different

242

predefined packages such as development utilities or packages with

243

debug information needed to investigate application problems or

244

profile applications.

</para>

<para>

The following image features are available for all images:

249

250

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

251

Allows Dropbear and OpenSSH to accept root logins

252

and logins from accounts having an empty password string.

253

</para></listitem>

254

255

Installs debug symbol packages for all packages installed

256

in a given image.

257

</para></listitem>

258

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

259

Makes an image suitable for development (e.g.

260

allows root logins without passwords and enables

261

post-installation logging).

262

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

263

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

264

additional information.

265

</para></listitem>

266

267

Installs development packages (headers and extra library

268

links) for all packages installed in a given image.

269

</para></listitem>

270

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

271

documentation packages for all packages installed in a

272

given image.

273

</para></listitem>

274

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

275

Sets the root password to an empty string, which allows

276

logins with a blank password.

277

</para></listitem>

278

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

279

Installs package management tools and preserves the package

280

manager database.

281

</para></listitem>

282

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

283

Enables logging postinstall script runs to

284

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

285

on first boot of the image on the target system.

286

<note>

287

To make the <filename>/var/log</filename> directory

288

on the target persistent, use the

289

290

variable by setting it to "no".

291

</note>

292

</para></listitem>

293

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

294

Installs ptest packages for all ptest-enabled recipes.

295

</para></listitem>

296

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

297

Creates an image whose root filesystem is read-only.

298

See the

299

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

300

section in the Yocto Project Development Tasks Manual for

301

more information.

302

</para></listitem>

303

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

304

Enables showing a splash screen during boot.

305

By default, this screen is provided by

306

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

307

customization.

308

If you prefer to use an alternative splash screen package,

309

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

310

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

311

image recipe or at the distro configuration level.

312

</para></listitem>

313

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

314

Installs static development packages, which are

315

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

316

all packages installed in a given image.

</para></listitem>

</itemizedlist>

</para>

<para>

Some image features are available only when you inherit the

323

324

class.

325

The current list of these valid features is as follows:

326

327

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

328

hardware acceleration codecs.

329

</para></listitem>

330

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

331

Installs an NFS server.

332

</para></listitem>

333

334

Installs profiling tools such as

335

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

336

and <filename>LTTng</filename>.

337

For general information on user-space tools, see the

338

<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>

339

manual.

340

</para></listitem>

341

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

342

Installs the Dropbear minimal SSH server.

343

</para></listitem>

344

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

345

Installs the OpenSSH SSH server, which is more

346

full-featured than Dropbear.

347

Note that if both the OpenSSH SSH server and the Dropbear

348

minimal SSH server are present in

349

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

350

precedence and Dropbear will not be installed.

351

</para></listitem>

352

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

353

Installs debugging tools such as

354

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

355

For information on GDB, see the

356

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

357

section in the Yocto Project Development Tasks Manual.

358

For information on tracing and profiling, see the

359

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

360

</para></listitem>

361

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

362

Installs a full SDK that runs on the device.

363

</para></listitem>

364

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

365

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

366

</para></listitem>

367

368

Installs the X server.

369

</para></listitem>

370

371

Installs the X server with a minimal environment.

372

</para></listitem>

373

374

Installs the OpenedHand Sato environment.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Feature Backfilling</title>

383

384

<para>

385

Sometimes it is necessary in the OpenEmbedded build system to extend

386

387

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

388

to control functionality that was previously enabled and not able

389

to be disabled.

390

For these cases, we need to add an

391

additional feature item to appear in one of these variables,

392

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

393

of the variables in their configuration to add the new feature

394

in order to retain the same overall level of functionality.

395

Thus, the OpenEmbedded build system has a mechanism to

396

automatically "backfill" these added features into existing

397

distro or machine configurations.

398

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

399

finding the

400

401

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

402

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

</para>

<para>

Because such features are backfilled by default into all

407

configurations as described in the previous paragraph, developers

408

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

409

prevent the backfilling from occurring.

410

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

411

412

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

413

variables for distro features and machine features respectively.

</para>

<para>

Here are two examples to help illustrate feature backfilling:

418

419

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

420

Previously, PulseAudio support was enabled within the Qt and

421

GStreamer frameworks.

422

Because of this, the feature is backfilled and thus

423

enabled for all distros through the

424

<filename>DISTRO_FEATURES_BACKFILL</filename>

425

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

426

However, your distro needs to disable the feature.

427

You can disable the feature without affecting

428

other existing distro configurations that need PulseAudio support

429

by adding "pulseaudio" to

430

<filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>

431

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

432

Adding the feature to this variable when it also

433

exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>

434

variable prevents the build system from adding the feature to

435

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

436

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

437

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

438

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

439

target devices.

440

Because of this, the feature is backfilled and thus enabled

441

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

442

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

443

However, your target device does not have this capability.

444

You can disable RTC support for your device without

445

affecting other machines that need RTC support

446

by adding the feature to your machine's

447

<filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>

448

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

449

Adding the feature to this variable when it also

450

exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>

451

variable prevents the build system from adding the feature to

452

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

453

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

</itemizedlist>

</para>

</section>

</chapter>

<!--

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

461

-->