summaryrefslogtreecommitdiffstats
path: root/documentation/poky-ref-manual/ref-classes.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/poky-ref-manual/ref-classes.xml')
-rw-r--r--documentation/poky-ref-manual/ref-classes.xml720
1 files changed, 0 insertions, 720 deletions
diff --git a/documentation/poky-ref-manual/ref-classes.xml b/documentation/poky-ref-manual/ref-classes.xml
deleted file mode 100644
index 2caea272a4..0000000000
--- a/documentation/poky-ref-manual/ref-classes.xml
+++ /dev/null
@@ -1,720 +0,0 @@
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<chapter id='ref-classes'>
6<title>Classes</title>
7
8<para>
9 Class files are used to abstract common functionality and share it amongst multiple
10 <filename>.bb</filename> files.
11 Any metadata usually found in a <filename>.bb</filename> file can also be placed in a class
12 file.
13 Class files are identified by the extension <filename>.bbclass</filename> and are usually placed
14 in a <filename>classes/</filename> directory beneath the
15 <filename>meta*/</filename> directory found in the
16 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
17 Class files can also be pointed to by BUILDDIR (e.g. <filename>build/</filename>)in the same way as
18 <filename>.conf</filename> files in the <filename>conf</filename> directory.
19 Class files are searched for in <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
20 using the same method by which <filename>.conf</filename> files are searched.
21</para>
22
23<para>
24 In most cases inheriting the class is enough to enable its features, although
25 for some classes you might need to set variables or override some of the
26 default behaviour.
27</para>
28
29<section id='ref-classes-base'>
30 <title>The base class - <filename>base.bbclass</filename></title>
31
32 <para>
33 The base class is special in that every <filename>.bb</filename>
34 file inherits it automatically.
35 This class contains definitions for standard basic
36 tasks such as fetching, unpacking, configuring (empty by default), compiling
37 (runs any <filename>Makefile</filename> present), installing (empty by default) and packaging
38 (empty by default).
39 These classes are often overridden or extended by other classes
40 such as <filename>autotools.bbclass</filename> or <filename>package.bbclass</filename>.
41 The class also contains some commonly used functions such as <filename>oe_runmake</filename>.
42 </para>
43</section>
44
45<section id='ref-classes-autotools'>
46 <title>Autotooled Packages - <filename>autotools.bbclass</filename></title>
47
48 <para>
49 Autotools (<filename>autoconf</filename>, <filename>automake</filename>,
50 and <filename>libtool</filename>) bring standardization.
51 This class defines a set of tasks (configure, compile etc.) that
52 work for all Autotooled packages.
53 It should usually be enough to define a few standard variables
54 and then simply <filename>inherit autotools</filename>.
55 This class can also work with software that emulates Autotools.
56 For more information, see the
57 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg-autotools'>Autotooled Package</ulink>"
58 section in the Yocto Project Development Manual.
59 </para>
60
61 <para>
62 It's useful to have some idea of how the tasks defined by this class work
63 and what they do behind the scenes.
64 <itemizedlist>
65 <listitem><para><filename>do_configure</filename> &dash; regenerates the
66 configure script (using <filename>autoreconf</filename>) and then launches it
67 with a standard set of arguments used during cross-compilation.
68 You can pass additional parameters to <filename>configure</filename> through the
69 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
70 </para></listitem>
71 <listitem><para><filename>do_compile</filename> &dash; runs <filename>make</filename> with
72 arguments that specify the compiler and linker.
73 You can pass additional arguments through
74 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
75 </para></listitem>
76 <listitem><para><filename>do_install</filename> &dash; runs <filename>make install</filename>
77 and passes a DESTDIR option, which takes its value from the standard
78 <filename><link linkend='var-DESTDIR'>DESTDIR</link></filename> variable.
79 </para></listitem>
80 </itemizedlist>
81 </para>
82</section>
83
84<section id='ref-classes-update-alternatives'>
85 <title>Alternatives - <filename>update-alternatives.bbclass</filename></title>
86
87 <para>
88 Several programs can fulfill the same or similar function and be installed with the same name.
89 For example, the <filename>ar</filename> command is available from the
90 <filename>busybox</filename>, <filename>binutils</filename> and
91 <filename>elfutils</filename> packages.
92 The <filename>update-alternatives.bbclass</filename> class handles renaming the
93 binaries so that multiple packages can be installed without conflicts.
94 The <filename>ar</filename> command still works regardless of which packages are installed
95 or subsequently removed.
96 The class renames the conflicting binary in each package and symlinks the highest
97 priority binary during installation or removal of packages.
98 </para>
99 <para>
100 Four variables control this class:
101 <itemizedlist>
102 <listitem><para><filename>ALTERNATIVE_NAME</filename> &dash; The name of the
103 binary that is replaced (<filename>ar</filename> in this example).</para></listitem>
104 <listitem><para><filename>ALTERNATIVE_LINK</filename> &dash; The path to
105 the resulting binary (<filename>/bin/ar</filename> in this example).</para></listitem>
106 <listitem><para><filename>ALTERNATIVE_PATH</filename> &dash; The path to the
107 real binary (<filename>/usr/bin/ar.binutils</filename> in this example).</para></listitem>
108 <listitem><para><filename>ALTERNATIVE_PRIORITY</filename> &dash; The priority of
109 the binary.
110 The version with the most features should have the highest priority.</para></listitem>
111 </itemizedlist>
112 </para>
113
114 <para>
115 Currently, the OpenEmbedded build system supports only one binary per package.
116 </para>
117</section>
118
119<section id='ref-classes-update-rc.d'>
120 <title>Initscripts - <filename>update-rc.d.bbclass</filename></title>
121
122 <para>
123 This class uses <filename>update-rc.d</filename> to safely install an
124 initialization script on behalf of the package.
125 The OpenEmbedded build system takes care of details such as making sure the script is stopped before
126 a package is removed and started when the package is installed.
127 Three variables control this class:
128 <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>,
129 <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and
130 <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>.
131 See the variable links for details.
132 </para>
133</section>
134
135<section id='ref-classes-binconfig'>
136 <title>Binary config scripts - <filename>binconfig.bbclass</filename></title>
137
138 <para>
139 Before <filename>pkg-config</filename> had become widespread, libraries shipped shell
140 scripts to give information about the libraries and include paths needed
141 to build software (usually named <filename>LIBNAME-config</filename>).
142 This class assists any recipe using such scripts.
143 </para>
144
145 <para>
146 During staging, BitBake installs such scripts into the
147 <filename>sysroots/</filename> directory.
148 BitBake also changes all paths to point into the <filename>sysroots/</filename>
149 directory so all builds that use the script will use the correct
150 directories for the cross compiling layout.
151 </para>
152</section>
153
154<section id='ref-classes-debian'>
155 <title>Debian renaming - <filename>debian.bbclass</filename></title>
156
157 <para>
158 This class renames packages so that they follow the Debian naming
159 policy (i.e. <filename>eglibc</filename> becomes <filename>libc6</filename>
160 and <filename>eglibc-devel</filename> becomes <filename>libc6-dev</filename>.
161 </para>
162</section>
163
164<section id='ref-classes-pkgconfig'>
165 <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title>
166
167 <para>
168 <filename>pkg-config</filename> brought standardization and this class aims to make its
169 integration smooth for all libraries that make use of it.
170 </para>
171
172 <para>
173 During staging, BitBake installs <filename>pkg-config</filename> data into the
174 <filename>sysroots/</filename> directory.
175 By making use of sysroot functionality within <filename>pkg-config</filename>,
176 this class no longer has to manipulate the files.
177 </para>
178</section>
179
180<section id='ref-classes-src-distribute'>
181 <title>Distribution of sources - <filename>src_distribute_local.bbclass</filename></title>
182
183 <para>
184 Many software licenses require that source files be provided along with the binaries.
185 To simplify this process, two classes were created:
186 <filename>src_distribute.bbclass</filename> and
187 <filename>src_distribute_local.bbclass</filename>.
188 </para>
189
190 <para>
191 The results of these classes are <filename>tmp/deploy/source/</filename>
192 subdirs with sources sorted by
193 <filename><link linkend='var-LICENSE'>LICENSE</link></filename> field.
194 If recipes list few licenses (or have entries like "Bitstream Vera"),
195 the source archive is placed in each license directory.
196 </para>
197
198 <para>
199 This class operates using three modes:
200 <itemizedlist>
201 <listitem><para><emphasis>copy:</emphasis> Copies the files to the
202 distribute directory.</para></listitem>
203 <listitem><para><emphasis>symlink:</emphasis> Symlinks the files to the
204 distribute directory.</para></listitem>
205 <listitem><para><emphasis>move+symlink:</emphasis> Moves the files into
206 the distribute directory and then symlinks them back.</para></listitem>
207 </itemizedlist>
208 </para>
209</section>
210
211<section id='ref-classes-perl'>
212 <title>Perl modules - <filename>cpan.bbclass</filename></title>
213
214 <para>
215 Recipes for Perl modules are simple.
216 These recipes usually only need to point to the source's archive and then inherit the
217 proper <filename>.bbclass</filename> file.
218 Building is split into two methods depending on which method the module authors used.
219 </para>
220
221 <para>
222 Modules that use old <filename>Makefile.PL</filename>-based build system require
223 <filename>cpan.bbclass</filename> in their recipes.
224 </para>
225
226 <para>
227 Modules that use <filename>Build.PL</filename>-based build system require
228 using <filename>cpan_build.bbclass</filename> in their recipes.
229 </para>
230</section>
231
232<section id='ref-classes-distutils'>
233 <title>Python extensions - <filename>distutils.bbclass</filename></title>
234
235 <para>
236 Recipes for Python extensions are simple.
237 These recipes usually only need to point to the source's archive and then inherit
238 the proper <filename>.bbclass</filename> file.
239 Building is split into two methods dependling on which method the module authors used.
240 </para>
241
242 <para>
243 Extensions that use an Autotools-based build system require Autotools and
244 <filename>distutils</filename>-based <filename>.bbclasse</filename> files in their recipes.
245 </para>
246
247 <para>
248 Extensions that use <filename>distutils</filename>-based build systems require
249 <filename>distutils.bbclass</filename> in their recipes.
250 </para>
251</section>
252
253<section id='ref-classes-devshell'>
254 <title>Developer Shell - <filename>devshell.bbclass</filename></title>
255
256 <para>
257 This class adds the <filename>devshell</filename> task.
258 Distribution policy dictates whether to include this class.
259 See the
260 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
261 in the Yocto Project Development Manual for more information about using <filename>devshell</filename>.
262 </para>
263</section>
264
265<section id='ref-classes-packagegroup'>
266 <title>Package Groups - <filename>packagegroup.bbclass</filename></title>
267
268 <para>
269 This class sets default values appropriate for package group recipes (such as
270 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>,
271 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>,
272 <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>,
273 and so forth.
274 It is highly recommended that all package group recipes inherit this class.
275 </para>
276 <para>
277 For information on how to use this class, see the
278 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Tasks</ulink>"
279 section in the Yocto Project Development Manual.
280 </para>
281 <para>
282 Previously, this class was named <filename>task.bbclass</filename>.
283 </para>
284</section>
285
286
287<section id='ref-classes-package'>
288 <title>Packaging - <filename>package*.bbclass</filename></title>
289
290 <para>
291 The packaging classes add support for generating packages from a build's
292 output.
293 The core generic functionality is in <filename>package.bbclass</filename>.
294 The code specific to particular package types is contained in various sub-classes such as
295 <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>,
296 and <filename>package_rpm.bbclass</filename>.
297 Most users will want one or more of these classes.
298 </para>
299
300 <para>
301 You can control the list of resulting package formats by using the
302 <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename>
303 variable defined in the <filename>local.conf</filename> configuration file,
304 which is located in the <filename>conf</filename> folder of the
305 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
306 When defining the variable, you can specify one or more package types.
307 Since images are generated from packages, a packaging class is
308 needed to enable image generation.
309 The first class listed in this variable is used for image generation.
310 </para>
311
312 <para>
313 The package class you choose can affect build-time performance and has space
314 ramifications.
315 In general, building a package with RPM takes about thirty percent more time as
316 compared to using IPK to build the same or similar package.
317 This comparison takes into account a complete build of the package with all
318 dependencies previously built.
319 The reason for this discrepancy is because the RPM package manager creates and
320 processes more metadata than the IPK package manager.
321 Consequently, you might consider setting <filename>PACKAGE_CLASSES</filename>
322 to "package_ipk" if you are building smaller systems.
323 </para>
324
325 <para>
326 Keep in mind, however, that RPM starts to provide more abilities than IPK due to
327 the fact that it processes more metadata.
328 For example, this information includes individual file types, file checksum generation
329 and evaluation on install, sparse file support, conflict detection and resolution
330 for multilib systems, ACID style upgrade, and repackaging abilities for rollbacks.
331 </para>
332
333 <para>
334 Another consideration for packages built using the RPM package manager is space.
335 For smaller systems, the extra space used for the Berkley Database and the amount
336 of metadata can affect your ability to do on-device upgrades.
337 </para>
338
339 <para>
340 You can find additional information on the effects of the package class at these
341 two Yocto Project mailing list links:
342 <itemizedlist>
343 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>
344 https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem>
345 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'>
346 https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem>
347 </itemizedlist>
348 </para>
349</section>
350
351<section id='ref-classes-kernel'>
352 <title>Building kernels - <filename>kernel.bbclass</filename></title>
353
354 <para>
355 This class handles building Linux kernels.
356 The class contains code to build all kernel trees.
357 All needed headers are staged into the
358 <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename>
359 directory to allow out-of-tree module builds using <filename>module.bbclass</filename>.
360 </para>
361
362 <para>
363 This means that each built kernel module is packaged separately and inter-module
364 dependencies are created by parsing the <filename>modinfo</filename> output.
365 If all modules are required, then installing the <filename>kernel-modules</filename>
366 package installs all packages with modules and various other kernel packages
367 such as <filename>kernel-vmlinux</filename>.
368 </para>
369
370 <para>
371 Various other classes are used by the kernel and module classes internally including
372 <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>,
373 <filename>module-base.bbclass</filename>, and <filename>linux-kernel-base.bbclass</filename>.
374 </para>
375</section>
376
377<section id='ref-classes-image'>
378 <title>Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>
379
380 <para>
381 These classes add support for creating images in several formats.
382 First, the root filesystem is created from packages using
383 one of the <filename>rootfs_*.bbclass</filename>
384 files (depending on the package format used) and then the image is created.
385 </para>
386
387 <para>
388 The <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename>
389 variable controls the types of images to generate.
390 </para>
391
392 <para>
393 The <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
394 variable controls the list of packages to install into the image.
395 </para>
396</section>
397
398<section id='ref-classes-sanity'>
399 <title>Host System sanity checks - <filename>sanity.bbclass</filename></title>
400
401 <para>
402 This class checks to see if prerequisite software is present so that
403 users can be notified of potential problems that might affect their build.
404 The class also performs basic user configuration checks from
405 the <filename>local.conf</filename> configuration file to
406 prevent common mistakes that cause build failures.
407 Distribution policy usually determines whether to include this class.
408 </para>
409</section>
410
411<section id='ref-classes-insane'>
412 <title>Generated output quality assurance checks - <filename>insane.bbclass</filename></title>
413
414 <para>
415 This class adds a step to the package generation process that sanity checks the
416 packages generated by the OpenEmbedded build system.
417 A range of checks are performed that check the build's output
418 for common problems that show up during runtime.
419 Distribution policy usually dictates whether to include this class.
420 </para>
421
422 <para>
423 You can configure the sanity checks so that specific test failures either raise a warning or
424 an error message.
425 Typically, failures for new tests generate a warning.
426 Subsequent failures for the same test would then generate an error message
427 once the metadata is in a known and good condition.
428 You use the <filename>WARN_QA</filename> variable to specify tests for which you
429 want to generate a warning message on failure.
430 You use the <filename>ERROR_QA</filename> variable to specify tests for which you
431 want to generate an error message on failure.
432 </para>
433
434 <para>
435 The following list shows the tests you can list with the <filename>WARN_QA</filename>
436 and <filename>ERROR_QA</filename> variables:
437 <itemizedlist>
438 <listitem><para><emphasis><filename>ldflags:</filename></emphasis>
439 Ensures that the binaries were linked with the
440 <filename>LDFLAGS</filename> options provided by the build system.
441 If this test fails, check that the <filename>LDFLAGS</filename> variable
442 is being passed to the linker command.</para></listitem>
443 <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
444 Checks for dynamic library load paths (rpaths) in the binaries that
445 by default on a standard system are searched by the linker (e.g.
446 <filename>/lib</filename> and <filename>/usr/lib</filename>).
447 While these paths will not cause any breakage, they do waste space and
448 are unnecessary.</para></listitem>
449 <listitem><para><emphasis><filename>rpaths:</filename></emphasis>
450 Checks for rpaths in the binaries that contain build system paths such
451 as <filename>TMPDIR</filename>.
452 If this test fails, bad <filename>-rpath</filename> options are being
453 passed to the linker commands and your binaries have potential security
454 issues.</para></listitem>
455 <listitem><para><emphasis><filename>dev-so:</filename></emphasis>
456 Checks that the <filename>.so</filename> symbolic links are in the
457 <filename>-dev</filename> package and not in any of the other packages.
458 In general, these symlinks are only useful for development purposes.
459 Thus, the <filename>-dev</filename> package is the correct location for
460 them.
461 Some very rare cases do exist for dynamically loaded modules where
462 these symlinks are needed instead in the main package.
463 </para></listitem>
464 <listitem><para><emphasis><filename>debug-files:</filename></emphasis>
465 Checks for <filename>.debug</filename> directories in anything but the
466 <filename>-dbg</filename> package.
467 The debug files should all be in the <filename>-dbg</filename> package.
468 Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
469 <listitem><para><emphasis><filename>arch:</filename></emphasis>
470 Checks the Executable and Linkable Format (ELF) type, bit size and endianness
471 of any binaries to ensure it matches the target architecture.
472 This test fails if any binaries don't match the type since there would be an
473 incompatibility.
474 Sometimes software, like bootloaders, might need to bypass this check.
475 </para></listitem>
476 <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
477 Checks that <filename>-dbg</filename> packages only depend on other
478 <filename>-dbg</filename> packages and not on any other types of packages,
479 which would cause a packaging bug.</para></listitem>
480 <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
481 Checks that <filename>-dev</filename> packages only depend on other
482 <filename>-dev</filename> packages and not on any other types of packages,
483 which would be a packaging bug.</para></listitem>
484 <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
485 Checks <filename>.pc</filename> files for any
486 <filename>TMPDIR/WORKDIR</filename> paths.
487 Any <filename>.pc</filename> file containing these paths is incorrect
488 since <filename>pkg-config</filename> itself adds the correct sysroot prefix
489 when the files are accessed.</para></listitem>
490 <listitem><para><emphasis><filename>la:</filename></emphasis>
491 Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
492 paths.
493 Any <filename>.la</filename> file continaing these paths is incorrect since
494 <filename>libtool</filename> adds the correct sysroot prefix when using the
495 files automatically itself.</para></listitem>
496 <listitem><para><emphasis><filename>desktop:</filename></emphasis>
497 Runs the <filename>desktop-file-validate</filename> program against any
498 <filename>.desktop</filename> files to validate their contents against
499 the specification for <filename>.desktop</filename> files.</para></listitem>
500 </itemizedlist>
501 </para>
502</section>
503
504<section id='ref-classes-siteinfo'>
505 <title>Autotools configuration data cache - <filename>siteinfo.bbclass</filename></title>
506
507 <para>
508 Autotools can require tests that must execute on the target hardware.
509 Since this is not possible in general when cross compiling, site information is
510 used to provide cached test results so these tests can be skipped over but
511 still make the correct values available.
512 The <filename><link linkend='structure-meta-site'>meta/site directory</link></filename>
513 contains test results sorted into different categories such as architecture, endianness, and
514 the <filename>libc</filename> used.
515 Site information provides a list of files containing data relevant to
516 the current build in the
517 <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable
518 that Autotools automatically picks up.
519 </para>
520
521 <para>
522 The class also provides variables like
523 <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename>
524 and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename>
525 that can be used elsewhere in the metadata.
526 </para>
527
528 <para>
529 Because this class is included from <filename>base.bbclass</filename>, it is always active.
530 </para>
531</section>
532
533<section id='ref-classes-useradd'>
534 <title>Adding Users - <filename>useradd.bbclass</filename></title>
535
536 <para>
537 If you have packages that install files that are owned by custom users or groups,
538 you can use this class to specify those packages and associate the users and groups
539 with those packages.
540 The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
541 recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
542 provides a simple exmample that shows how to add three
543 users and groups to two packages.
544 See the <filename>useradd-example.bb</filename> for more information on how to
545 use this class.
546 </para>
547</section>
548
549<section id='ref-classes-externalsrc'>
550 <title>Using External Source - <filename>externalsrc.bbclass</filename></title>
551
552 <para>
553 You can use this class to build software from source code that is external to the
554 OpenEmbedded build system.
555 In other words, your source code resides in an external tree outside of the Yocto Project.
556 Building software from an external source tree means that the normal fetch, unpack, and
557 patch process is not used.
558 </para>
559
560 <para>
561 To use the class, you need to define the
562 <link linkend='var-S'><filename>S</filename></link> variable to point to the directory that contains the source files.
563 You also need to have your recipe inherit the <filename>externalsrc.bbclass</filename> class.
564 </para>
565
566 <para>
567 This class expects the source code to support recipe builds that use the
568 <link linkend='var-B'><filename>B</filename></link> variable to point to the directory in
569 which the OpenEmbedded build system places the generated objects built from the recipes.
570 By default, the <filename>B</filename> directory is set to the following, which is separate from the
571 Source Directory (<filename>S</filename>):
572 <literallayout class='monospaced'>
573 ${WORKDIR}/${BPN}/{PV}/
574 </literallayout>
575 See the glossary entries for the
576 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
577 <link linkend='var-BPN'><filename>BPN</filename></link>,
578 <link linkend='var-PV'><filename>PV</filename></link>,
579 <link linkend='var-S'><filename>S</filename></link>, and
580 <link linkend='var-B'><filename>B</filename></link> for more information.
581 </para>
582
583 <para>
584 You can build object files in the external tree by setting the
585 <filename>B</filename> variable equal to <filename>"${S}"</filename>.
586 However, this practice does not work well if you use the source for more than one variant
587 (i.e., "natives" such as <filename>quilt-native</filename>,
588 or "crosses" such as <filename>gcc-cross</filename>).
589 So, be sure there are no "native", "cross", or "multilib" variants of the recipe.
590 </para>
591
592 <para>
593 If you do want to build different variants of a recipe, you can use the
594 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> variable.
595 When you do, the <link linkend='var-B'><filename>B</filename></link> variable must support the
596 recipe's ability to build variants in different working directories.
597 Most autotools-based recipes support separating these directories.
598 The OpenEmbedded build system defaults to using separate directories for <filename>gcc</filename>
599 and some kernel recipes.
600 Alternatively, you can make sure that separate recipes exist that each
601 use the <filename>BBCLASSEXTEND</filename> variable to build each variant.
602 The separate recipes can inherit a single target recipe.
603 </para>
604
605 <para>
606 For information on how to use this class, see the
607 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building
608 Software from an External Source</ulink>" section in the Yocto Project Development Manual.
609 </para>
610</section>
611
612<section id='ref-classes-others'>
613 <title>Other Classes</title>
614
615 <para>
616 Thus far, this chapter has discussed only the most useful and important
617 classes.
618 However, other classes exist within the <filename>meta/classes</filename> directory
619 in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
620 You can examine the <filename>.bbclass</filename> files directly for more
621 information.
622 </para>
623</section>
624
625<!-- Undocumented classes are:
626 allarch.bbclass
627 archive*.bbclass
628 binconfig.bbclass
629 blacklist.bbclass
630 bootimg.bbclass
631 boot-directdisk.bbclass
632 bugzilla.bbclass
633 buildhistory.bbclass
634 buildstats.bbclass
635 ccache.bbclass
636 chrpath.bbclass
637 cmake.bbclass
638 cml1.bbclass
639 copyleft_compliance.bbclass
640 core-image.bbclass
641 cross.bbclass
642 cross-canadian.bbclass
643 crosssdk.bbclass
644 deploy.bbclass
645 distrodata.bbclass
646 dummy.bbclass
647 gconf.bbclass
648 gettext.bbclass
649 gnomebase.bbclass
650 gnome.bbclass
651 gtk-doc.bbclass
652 gtk-icon-cache.bbclass
653 gzipnative.bbclass
654 icecc.bbclass
655 image-empty.bbclass
656 image-live.bbclass
657 image-vmdk.bbclass
658 image-mklibs.bbclass
659 image-prelink.bbclass
660 image-swab.bbclass
661 imagetest-dummy.bbclass
662 imagetest-qemu.bbclass
663 image_types.bbclass
664 image_types_uboot.bbclass
665 insserv.bbclass
666 kernel-arch.bbclass
667 kernel-yocto.bbclass
668 lib_package.bbclass
669 linux-kernel-base.bbclass
670 license.bbclass
671 logging.bbclass
672 meta.bbclass
673 metadata_scm.bbclass
674 mime.bbclass
675 mirrors.bbclass
676 multilib*.bbclass
677 native.bbclass
678 nativesdk.bbclass
679 oelint.bbclass
680 own-mirrors.bbclass
681 packagedata.bbclass
682 packageinfo.bbclass
683 patch.bbclass
684 perlnative.bbclass
685 pkg_distribute.bbclass
686 pkg_metainfo.bbclass
687 populate_sdk*.bbclass
688 prexport.bbclass
689 primport.bbclass
690 prserv.bbclass
691 python-dir.bbclass
692 pythonnative.bbclass
693 qemu.bbclass
694 qmake*.bbclass
695 qt4*.bbclass
696 recipe_sanity.bbclass
697 relocatable.bbclass
698 rm_work.bbclass
699 scons.bbclass
700 sdl.bbclass
701 setuptools.bbclass
702 sip.bbclass
703 siteconfig.bbclass
704 sourcepkg.bbclass
705 sstate.bbclass
706 staging.bbclass
707 syslinux.bbclass
708 terminal.bbclass
709 tinderclient.bbclass
710 toolchain-scripts.bbclass
711 typecheck.bbclass
712 utility-tasks.bbclass
713 utils.bbclass
714-->
715
716
717</chapter>
718<!--
719vim: expandtab tw=80 ts=4
720-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-24 02:37:38 +0000