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>

147

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

148

support.</para></listitem>

149

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

150

Include DirectFB support.

151

</para></listitem>

152

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

153

supporting for devices with internal HDD/Microdrive for

154

storing files (instead of Flash only devices).

155

</para></listitem>

156

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

157

support.</para></listitem>

158

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

159

</para></listitem>

160

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

161

</para></listitem>

162

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

163

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

164

</para></listitem>

165

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

166

support (for mounting NFS exports on device).

167

</para></listitem>

168

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

169

Include the Open Graphics Library, which is a

170

cross-language, multi-platform application programming

171

interface used for rendering two and three-dimensional

172

graphics.</para></listitem>

173

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

174

support.</para></listitem>

175

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

176

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

177

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

178

support.</para></listitem>

179

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

180

the package tests where supported by individual recipes.

181

For more information on package tests, see the

182

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

183

section in the Yocto Project Development Manual.

184

</para></listitem>

185

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

186

client support (for mounting Samba/Microsoft Windows shares

187

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

188

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

189

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

190

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

191

starting of services, reduced shell overhead, and other

192

features.

193

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

194

distributions.</para></listitem>

195

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

196

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

197

</para></listitem>

198

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

199

support (allows to connect external keyboard, mouse,

200

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

201

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

202

Wayland display server protocol and the library that

203

supports it.</para></listitem>

204

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

205

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

206

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

207

and libraries.</para></listitem>

</itemizedlist>

</para>

</section>

<title>Image Features</title>

214

215

<para>

216

The contents of images generated by the OpenEmbedded build system

217

can be controlled by the

and

variables that you typically configure in your image recipes.

222

Through these variables, you can add several different

223

predefined packages such as development utilities or packages with

224

debug information needed to investigate application problems or

225

profile applications.

</para>

<para>

The following image features are available for all images:

230

231

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

232

Allows Dropbear and OpenSSH to accept root logins

233

and logins from accounts having an empty password string.

234

</para></listitem>

235

236

Installs debug symbol packages for all packages installed

237

in a given image.

238

</para></listitem>

239

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

240

Makes an image suitable for development (e.g.

241

allows root logins without passwords and enables

242

post-installation logging).

243

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

244

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

245

additional information.

246

</para></listitem>

247

248

Installs development packages (headers and extra library

249

links) for all packages installed in a given image.

250

</para></listitem>

251

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

252

documentation packages for all packages installed in a

253

given image.

254

</para></listitem>

255

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

256

Sets the root password to an empty string, which allows

257

logins with a blank password.

258

</para></listitem>

259

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

260

Installs package management tools and preserves the package

261

manager database.

262

</para></listitem>

263

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

264

Enables logging postinstall script runs to

265

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

266

on first boot of the image on the target system.

267

</para></listitem>

268

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

269

Installs ptest packages for all ptest-enabled recipes.

270

</para></listitem>

271

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

272

Creates an image whose root filesystem is read-only.

273

See the

274

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

275

section in the Yocto Project Development Manual for more

276

information.

277

</para></listitem>

278

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

279

Enables showing a splash screen during boot.

280

By default, this screen is provided by

281

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

282

customization.

283

If you prefer to use an alternative splash screen package,

284

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

285

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

286

image recipe or at the distro configuration level.

287

</para></listitem>

288

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

289

Installs static development packages, which are

290

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

291

all packages installed in a given image.

</para></listitem>

</itemizedlist>

</para>

<para>

Some image features are available only when you inherit the

298

299

class.

300

The current list of these valid features is as follows:

301

302

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

303

Eclipse remote debugging support.

304

</para></listitem>

305

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

306

hardware acceleration codecs.

307

</para></listitem>

308

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

309

Installs an NFS server.

310

</para></listitem>

Patrick Williams

d8c66bc

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

[diff] [blame]

311

312

Installs profiling tools such as

313

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

314

and <filename>LTTng</filename>.

315

For general information on user-space tools, see the

316

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

317

</para></listitem>

318

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

319

Installs the Dropbear minimal SSH server.

320

</para></listitem>

321

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

322

Installs the OpenSSH SSH server, which is more

323

full-featured than Dropbear.

324

Note that if both the OpenSSH SSH server and the Dropbear

325

minimal SSH server are present in

326

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

327

precedence and Dropbear will not be installed.

328

</para></listitem>

329

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

330

Installs debugging tools such as

331

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

332

For information on GDB, see the

333

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

334

section in the Yocto Project Development Manual.

335

For information on tracing and profiling, see the

336

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

337

</para></listitem>

Patrick Williams

c124f4f

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

[diff] [blame]

338

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

339

Installs a full SDK that runs on the device.

340

</para></listitem>

341

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

342

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

343

</para></listitem>

344

345

Installs the X server.

346

</para></listitem>

347

348

Installs the X server with a minimal environment.

349

</para></listitem>

350

351

Installs the OpenedHand Sato environment.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Feature Backfilling</title>

360

361

<para>

362

Sometimes it is necessary in the OpenEmbedded build system to extend

363

364

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

365

to control functionality that was previously enabled and not able

366

to be disabled.

367

For these cases, we need to add an

368

additional feature item to appear in one of these variables,

369

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

370

of the variables in their configuration to add the new feature

371

in order to retain the same overall level of functionality.

372

Thus, the OpenEmbedded build system has a mechanism to

373

automatically "backfill" these added features into existing

374

distro or machine configurations.

375

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

376

finding the

377

378

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

379

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

</para>

<para>

Because such features are backfilled by default into all

384

configurations as described in the previous paragraph, developers

385

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

386

prevent the backfilling from occurring.

387

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

388

389

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

390

variables for distro features and machine features respectively.

</para>

<para>

Here are two examples to help illustrate feature backfilling:

395

396

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

397

Previously, PulseAudio support was enabled within the Qt and

398

GStreamer frameworks.

399

Because of this, the feature is backfilled and thus

400

enabled for all distros through the

401

<filename>DISTRO_FEATURES_BACKFILL</filename>

402

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

403

However, your distro needs to disable the feature.

404

You can disable the feature without affecting

405

other existing distro configurations that need PulseAudio support

406

by adding "pulseaudio" to

407

<filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>

408

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

409

Adding the feature to this variable when it also

410

exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>

411

variable prevents the build system from adding the feature to

412

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

413

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

414

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

415

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

416

target devices.

417

Because of this, the feature is backfilled and thus enabled

418

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

419

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

420

However, your target device does not have this capability.

421

You can disable RTC support for your device without

422

affecting other machines that need RTC support

423

by adding the feature to your machine's

424

<filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>

425

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

426

Adding the feature to this variable when it also

427

exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>

428

variable prevents the build system from adding the feature to

429

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

430

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

</itemizedlist>

</para>

</section>

</chapter>

<!--

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

438

-->