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

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>

311

312

Supports Qt4/X11 and demo applications.

313

</para></listitem>

314

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

315

Installs the Dropbear minimal SSH server.

316

</para></listitem>

317

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

318

Installs the OpenSSH SSH server, which is more

319

full-featured than Dropbear.

320

Note that if both the OpenSSH SSH server and the Dropbear

321

minimal SSH server are present in

322

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

323

precedence and Dropbear will not be installed.

324

</para></listitem>

325

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

326

Installs debugging tools such as

327

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

328

For information on GDB, see the

329

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

330

section in the Yocto Project Development Manual.

331

For information on tracing and profiling, see the

332

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

333

</para></listitem>

334

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

335

Installs profiling tools such as

336

<filename>oprofile</filename>, <filename>exmap</filename>,

337

and <filename>LTTng</filename>.

338

For general information on user-space tools, see the

339

"<ulink url='&YOCTO_DOCS_ADT_URL;#user-space-tools'>User-Space Tools</ulink>"

340

section in the Yocto Project Application Developer's

341

Guide.

342

</para></listitem>

343

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

344

Installs a full SDK that runs on the device.

345

</para></listitem>

346

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

347

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

348

</para></listitem>

349

350

Installs the X server.

351

</para></listitem>

352

353

Installs the X server with a minimal environment.

354

</para></listitem>

355

356

Installs the OpenedHand Sato environment.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Feature Backfilling</title>

365

366

<para>

367

Sometimes it is necessary in the OpenEmbedded build system to extend

368

369

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

370

to control functionality that was previously enabled and not able

371

to be disabled.

372

For these cases, we need to add an

373

additional feature item to appear in one of these variables,

374

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

375

of the variables in their configuration to add the new feature

376

in order to retain the same overall level of functionality.

377

Thus, the OpenEmbedded build system has a mechanism to

378

automatically "backfill" these added features into existing

379

distro or machine configurations.

380

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

381

finding the

382

383

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

384

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

</para>

<para>

Because such features are backfilled by default into all

389

configurations as described in the previous paragraph, developers

390

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

391

prevent the backfilling from occurring.

392

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

393

394

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

395

variables for distro features and machine features respectively.

</para>

<para>

Here are two examples to help illustrate feature backfilling:

400

401

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

402

Previously, PulseAudio support was enabled within the Qt and

403

GStreamer frameworks.

404

Because of this, the feature is backfilled and thus

405

enabled for all distros through the

406

<filename>DISTRO_FEATURES_BACKFILL</filename>

407

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

408

However, your distro needs to disable the feature.

409

You can disable the feature without affecting

410

other existing distro configurations that need PulseAudio support

411

by adding "pulseaudio" to

412

<filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>

413

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

414

Adding the feature to this variable when it also

415

exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>

416

variable prevents the build system from adding the feature to

417

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

418

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

419

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

420

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

421

target devices.

422

Because of this, the feature is backfilled and thus enabled

423

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

424

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

425

However, your target device does not have this capability.

426

You can disable RTC support for your device without

427

affecting other machines that need RTC support

428

by adding the feature to your machine's

429

<filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>

430

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

431

Adding the feature to this variable when it also

432

exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>

433

variable prevents the build system from adding the feature to

434

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

435

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

</itemizedlist>

</para>

</section>

</chapter>

<!--

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

443

-->