Blame - import-layers/yocto-poky/documentation/ref-manual/ref-features.xml - mdmillerii/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>

145

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

146

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

Patrick Williams

c0f7c04

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

[diff] [blame]

147

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

148

BlueZ Version 5, which provides core Bluetooth layers and

149

protocols support.

150

<note>

151

The default value for the

152

153

variable includes "bluetooth", which causes bluez5

154

to be backfilled in for bluetooth support.

155

If you do not want bluez5 backfilled and would rather

156

use bluez4, you need to use the

variable as follows:

DISTRO_FEATURES_BACKFILL_CONSIDERED = "bluez5"

161

</literallayout>

162

Setting this variable tells the OpenEmbedded build

163

system that you have considered but ruled

164

out using the bluez5 feature and that bluez4 will be

165

used.

166

</note>

167

</para></listitem>

Patrick Williams

c124f4f

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

[diff] [blame]

168

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

169

support.</para></listitem>

170

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

171

Include DirectFB support.

172

</para></listitem>

173

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

174

supporting for devices with internal HDD/Microdrive for

175

storing files (instead of Flash only devices).

176

</para></listitem>

177

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

178

support.</para></listitem>

179

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

180

</para></listitem>

181

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

182

</para></listitem>

183

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

184

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

185

</para></listitem>

186

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

187

support (for mounting NFS exports on device).

188

</para></listitem>

189

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

190

Include the Open Graphics Library, which is a

191

cross-language, multi-platform application programming

192

interface used for rendering two and three-dimensional

193

graphics.</para></listitem>

194

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

195

support.</para></listitem>

196

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

197

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

198

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

199

support.</para></listitem>

200

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

201

the package tests where supported by individual recipes.

202

For more information on package tests, see the

203

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

204

section in the Yocto Project Development Manual.

205

</para></listitem>

206

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

207

client support (for mounting Samba/Microsoft Windows shares

208

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

209

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

210

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

211

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

212

starting of services, reduced shell overhead, and other

213

features.

214

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

215

distributions.</para></listitem>

216

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

217

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

218

</para></listitem>

219

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

220

support (allows to connect external keyboard, mouse,

221

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

222

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

223

Wayland display server protocol and the library that

224

supports it.</para></listitem>

225

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

226

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

227

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

228

and libraries.</para></listitem>

</itemizedlist>

</para>

</section>

<title>Image Features</title>

235

236

<para>

237

The contents of images generated by the OpenEmbedded build system

238

can be controlled by the

and

variables that you typically configure in your image recipes.

243

Through these variables, you can add several different

244

predefined packages such as development utilities or packages with

245

debug information needed to investigate application problems or

246

profile applications.

</para>

<para>

The following image features are available for all images:

251

252

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

253

Allows Dropbear and OpenSSH to accept root logins

254

and logins from accounts having an empty password string.

255

</para></listitem>

256

257

Installs debug symbol packages for all packages installed

258

in a given image.

259

</para></listitem>

260

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

261

Makes an image suitable for development (e.g.

262

allows root logins without passwords and enables

263

post-installation logging).

264

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

265

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

266

additional information.

267

</para></listitem>

268

269

Installs development packages (headers and extra library

270

links) for all packages installed in a given image.

271

</para></listitem>

272

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

273

documentation packages for all packages installed in a

274

given image.

275

</para></listitem>

276

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

277

Sets the root password to an empty string, which allows

278

logins with a blank password.

279

</para></listitem>

280

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

281

Installs package management tools and preserves the package

282

manager database.

283

</para></listitem>

284

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

285

Enables logging postinstall script runs to

286

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

287

on first boot of the image on the target system.

288

</para></listitem>

289

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

290

Installs ptest packages for all ptest-enabled recipes.

291

</para></listitem>

292

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

293

Creates an image whose root filesystem is read-only.

294

See the

295

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

296

section in the Yocto Project Development Manual for more

297

information.

298

</para></listitem>

299

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

300

Enables showing a splash screen during boot.

301

By default, this screen is provided by

302

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

303

customization.

304

If you prefer to use an alternative splash screen package,

305

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

306

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

307

image recipe or at the distro configuration level.

308

</para></listitem>

309

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

310

Installs static development packages, which are

311

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

312

all packages installed in a given image.

</para></listitem>

</itemizedlist>

</para>

<para>

Some image features are available only when you inherit the

319

320

class.

321

The current list of these valid features is as follows:

322

323

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

324

Eclipse remote debugging support.

325

</para></listitem>

326

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

327

hardware acceleration codecs.

328

</para></listitem>

329

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

330

Installs an NFS server.

331

</para></listitem>

Patrick Williams

d8c66bc

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

[diff] [blame]

332

333

Installs profiling tools such as

334

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

335

and <filename>LTTng</filename>.

336

For general information on user-space tools, see the

337

<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]

338

</para></listitem>

339

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

340

Installs the Dropbear minimal SSH server.

341

</para></listitem>

342

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

343

Installs the OpenSSH SSH server, which is more

344

full-featured than Dropbear.

345

Note that if both the OpenSSH SSH server and the Dropbear

346

minimal SSH server are present in

347

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

348

precedence and Dropbear will not be installed.

349

</para></listitem>

350

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

351

Installs debugging tools such as

352

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

353

For information on GDB, see the

354

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

355

section in the Yocto Project Development Manual.

356

For information on tracing and profiling, see the

357

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

358

</para></listitem>

Patrick Williams

c124f4f

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

[diff] [blame]

359

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

360

Installs a full SDK that runs on the device.

361

</para></listitem>

362

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

363

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

364

</para></listitem>

365

366

Installs the X server.

367

</para></listitem>

368

369

Installs the X server with a minimal environment.

370

</para></listitem>

371

372

Installs the OpenedHand Sato environment.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Feature Backfilling</title>

381

382

<para>

383

Sometimes it is necessary in the OpenEmbedded build system to extend

384

385

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

386

to control functionality that was previously enabled and not able

387

to be disabled.

388

For these cases, we need to add an

389

additional feature item to appear in one of these variables,

390

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

391

of the variables in their configuration to add the new feature

392

in order to retain the same overall level of functionality.

393

Thus, the OpenEmbedded build system has a mechanism to

394

automatically "backfill" these added features into existing

395

distro or machine configurations.

396

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

397

finding the

398

399

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

400

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

</para>

<para>

Because such features are backfilled by default into all

405

configurations as described in the previous paragraph, developers

406

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

407

prevent the backfilling from occurring.

408

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

409

410

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

411

variables for distro features and machine features respectively.

</para>

<para>

Here are two examples to help illustrate feature backfilling:

416

417

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

418

Previously, PulseAudio support was enabled within the Qt and

419

GStreamer frameworks.

420

Because of this, the feature is backfilled and thus

421

enabled for all distros through the

422

<filename>DISTRO_FEATURES_BACKFILL</filename>

423

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

424

However, your distro needs to disable the feature.

425

You can disable the feature without affecting

426

other existing distro configurations that need PulseAudio support

427

by adding "pulseaudio" to

428

<filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>

429

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

430

Adding the feature to this variable when it also

431

exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>

432

variable prevents the build system from adding the feature to

433

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

434

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

435

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

436

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

437

target devices.

438

Because of this, the feature is backfilled and thus enabled

439

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

440

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

441

However, your target device does not have this capability.

442

You can disable RTC support for your device without

443

affecting other machines that need RTC support

444

by adding the feature to your machine's

445

<filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>

446

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

447

Adding the feature to this variable when it also

448

exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>

449

variable prevents the build system from adding the feature to

450

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

451

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

</itemizedlist>

</para>

</section>

</chapter>

<!--

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

459

-->