summaryrefslogtreecommitdiffstats
path: root/documentation/poky-ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scrott.m.rifenbark@intel.com>2010-11-04 21:12:46 +0000
committerRichard Purdie <rpurdie@linux.intel.com>2010-11-04 21:12:46 +0000
commit09ef6a4e130ac2fd157dbf4d236e4a247ed8da88 (patch)
treee28069b6f2e9dd63109140920e8d8f0ded364699 /documentation/poky-ref-manual
parent890a794e38f2d11ec0dd6e39e5ab77a929cb51d9 (diff)
downloadpoky-09ef6a4e130ac2fd157dbf4d236e4a247ed8da88.tar.gz
Poky Reference Manual: Completed editing pass of Chapter 3.
I completed the editing pass of this chapter by doing sections 3.3.3 on. Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Diffstat (limited to 'documentation/poky-ref-manual')
-rw-r--r--documentation/poky-ref-manual/extendpoky.xml773
1 files changed, 389 insertions, 384 deletions
diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml
index 763670e17c..4fc30534ba 100644
--- a/documentation/poky-ref-manual/extendpoky.xml
+++ b/documentation/poky-ref-manual/extendpoky.xml
@@ -109,6 +109,7 @@ inherit autotools gettext
109 </para> 109 </para>
110 110
111 </section> 111 </section>
112
112 <section id='usingpoky-extend-addpkg-makefile'> 113 <section id='usingpoky-extend-addpkg-makefile'>
113 <title>Makefile-Based Package</title> 114 <title>Makefile-Based Package</title>
114 <para> 115 <para>
@@ -160,6 +161,7 @@ do_install () {
160 </programlisting> 161 </programlisting>
161 162
162 </section> 163 </section>
164
163 <section id='usingpoky-extend-addpkg-files'> 165 <section id='usingpoky-extend-addpkg-files'>
164 <title>Controlling Package Content</title> 166 <title>Controlling Package Content</title>
165 <para> 167 <para>
@@ -348,8 +350,7 @@ RRECOMMENDS_task-custom-tools = "\
348 </section> 350 </section>
349 351
350 <section id='usingpoky-extend-customimage-imagefeatures'> 352 <section id='usingpoky-extend-customimage-imagefeatures'>
351 <title>Customising Images Using Custom <glossterm> 353 <title>Customising Images Using Custom IMAGE_FEATURES</title>
352 <link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm></title>
353 <para> 354 <para>
354 Ultimately users might want to add extra image "features" as used by Poky with the 355 Ultimately users might want to add extra image "features" as used by Poky with the
355 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> 356 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
@@ -401,107 +402,108 @@ DISTRO_EXTRA_RDEPENDS += "strace"
401 dependencies - it only rebuilds the specified package. 402 dependencies - it only rebuilds the specified package.
402 </para> 403 </para>
403 <programlisting> 404 <programlisting>
404bitbake -c clean task-boot task-base task-poky 405$ bitbake -c clean task-boot task-base task-poky
405bitbake poky-image-sato 406$ bitbake poky-image-sato
406 </programlisting> 407 </programlisting>
407 </section> 408 </section>
408 409
409 </section> 410 </section>
410 411
411<section id="platdev-newmachine"> 412 <section id="platdev-newmachine">
412 <title>Porting Poky to a New Machine</title> 413 <title>Porting Poky to a New Machine</title>
413 <para>
414 Adding a new machine to Poky is a straightforward process.
415 This section provides information that gives you an idea of the changes you must make.
416 The information covers adding machines similar to those Poky already supports.
417 Although well within the capabilities of Poky, adding a totally new architecture might require
418 changes to <filename>gcc/glibc</filename> and to the site information.
419 Consequently, the information is beyond the scope of this manual.
420 </para>
421
422 <section id="platdev-newmachine-conffile">
423 <title>Adding the Machine Configuration File</title>
424 <para>
425 To add a machine configuration you need to add a <filename>.conf</filename> file
426 with details of the device being added to <filename>conf/machine/</filename>.
427 The name of the file determines the name Poky uses to reference the new machine.
428 </para>
429 <para> 414 <para>
430 The most important variables to set in this file are <glossterm> 415 Adding a new machine to Poky is a straightforward process.
431 <link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm> 416 This section provides information that gives you an idea of the changes you must make.
432 (e.g. "arm"), <glossterm><link linkend='var-PREFERRED_PROVIDER'> 417 The information covers adding machines similar to those Poky already supports.
433 PREFERRED_PROVIDER</link></glossterm>_virtual/kernel (see below) and 418 Although well within the capabilities of Poky, adding a totally new architecture might require
434 <glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES 419 changes to <filename>gcc/glibc</filename> and to the site information.
435 </link></glossterm> (e.g. "kernel26 apm screen wifi"). 420 Consequently, the information is beyond the scope of this manual.
436 You might also need other variables like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE
437 </link></glossterm> (e.g. "115200 ttyS0"), <glossterm>
438 <link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link>
439 </glossterm> (e.g. "zImage") and <glossterm><link linkend='var-IMAGE_FSTYPES'>
440 IMAGE_FSTYPES</link></glossterm> (e.g. "tar.gz jffs2").
441 You can find full details on these variables in the reference section.
442 You can leverage many existing machine <filename>.conf</filename> files from
443 <filename>meta/conf/machine/</filename>.
444 </para> 421 </para>
445 </section>
446 422
447 <section id="platdev-newmachine-kernel"> 423 <section id="platdev-newmachine-conffile">
448 <title>Adding a Kernel for the Machine</title> 424 <title>Adding the Machine Configuration File</title>
449 <para> 425 <para>
450 Poky needs to be able to build a kernel for the machine. 426 To add a machine configuration you need to add a <filename>.conf</filename> file
451 You need to either create a new kernel recipe for this machine, or extend an 427 with details of the device being added to <filename>conf/machine/</filename>.
452 existing recipe. 428 The name of the file determines the name Poky uses to reference the new machine.
453 You can find several kernel examples in the <filename>meta/recipes-kernel/linux</filename> 429 </para>
454 directory that can be used as references. 430 <para>
455 </para> 431 The most important variables to set in this file are <glossterm>
456 <para> 432 <link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm>
457 If you are creating a new recipe, the "normal" recipe-writing rules apply for setting 433 (e.g. "arm"), <glossterm><link linkend='var-PREFERRED_PROVIDER'>
458 up a <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. 434 PREFERRED_PROVIDER</link></glossterm>_virtual/kernel (see below) and
459 This means specifying any necessary patches and setting <glossterm> 435 <glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES
460 <link linkend='var-S'>S</link></glossterm> to point at the source code. 436 </link></glossterm> (e.g. "kernel26 apm screen wifi").
461 You need to create a "configure" task that configures the unpacked kernel with a defconfig. 437 You might also need other variables like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE
462 You can do this by using a <filename>make defconfig</filename> command or 438 </link></glossterm> (e.g. "115200 ttyS0"), <glossterm>
463 more commonly by copying in a suitable defconfig and and then running 439 <link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link>
464 <filename>make oldconfig</filename>. 440 </glossterm> (e.g. "zImage") and <glossterm><link linkend='var-IMAGE_FSTYPES'>
465 By making use of "inherit kernel" and potentially some of the 441 IMAGE_FSTYPES</link></glossterm> (e.g. "tar.gz jffs2").
466 <filename>linux-*.inc</filename> files, most other functionality is 442 You can find full details on these variables in the reference section.
467 centralized and the the defaults of the class normally work well. 443 You can leverage many existing machine <filename>.conf</filename> files from
468 </para> 444 <filename>meta/conf/machine/</filename>.
469 <para> 445 </para>
470 If you are extending an existing kernel, it is usually a matter of adding a 446 </section>
471 suitable <filename>defconfig</filename> file. 447
472 The file needs to be added into a location similar to <filename>defconfig</filename> files 448 <section id="platdev-newmachine-kernel">
473 used for other machines in a given kernel. 449 <title>Adding a Kernel for the Machine</title>
474 A possible way to do this is by listing the file in the 450 <para>
475 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> 451 Poky needs to be able to build a kernel for the machine.
476 and adding the machine to the expression in 452 You need to either create a new kernel recipe for this machine, or extend an
477 <glossterm><link linkend='var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</link></glossterm>: 453 existing recipe.
478 </para> 454 You can find several kernel examples in the <filename>meta/recipes-kernel/linux</filename>
479 <programlisting> 455 directory that can be used as references.
456 </para>
457 <para>
458 If you are creating a new recipe, the "normal" recipe-writing rules apply for setting
459 up a <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
460 This means specifying any necessary patches and setting <glossterm>
461 <link linkend='var-S'>S</link></glossterm> to point at the source code.
462 You need to create a "configure" task that configures the unpacked kernel with a defconfig.
463 You can do this by using a <filename>make defconfig</filename> command or
464 more commonly by copying in a suitable defconfig and and then running
465 <filename>make oldconfig</filename>.
466 By making use of "inherit kernel" and potentially some of the
467 <filename>linux-*.inc</filename> files, most other functionality is
468 centralized and the the defaults of the class normally work well.
469 </para>
470 <para>
471 If you are extending an existing kernel, it is usually a matter of adding a
472 suitable <filename>defconfig</filename> file.
473 The file needs to be added into a location similar to <filename>defconfig</filename> files
474 used for other machines in a given kernel.
475 A possible way to do this is by listing the file in the
476 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>
477 and adding the machine to the expression in
478 <glossterm><link linkend='var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</link></glossterm>:
479 </para>
480 <programlisting>
480COMPATIBLE_MACHINE = '(qemux86|qemumips)' 481COMPATIBLE_MACHINE = '(qemux86|qemumips)'
481 </programlisting> 482 </programlisting>
482 </section> 483 </section>
483 484
484 <section id="platdev-newmachine-formfactor"> 485 <section id="platdev-newmachine-formfactor">
485 <title>Adding a Formfactor Configuration File</title> 486 <title>Adding a Formfactor Configuration File</title>
486 <para> 487 <para>
487 A formfactor configuration file provides information about the 488 A formfactor configuration file provides information about the
488 target hardware on which Poky is running, and that Poky cannot 489 target hardware on which Poky is running, and that Poky cannot
489 obtain from other sources such as the kernel. Some examples of 490 obtain from other sources such as the kernel.
490 information contained in a formfactor configuration file include 491 Some examples of information contained in a formfactor configuration file include
491 framebuffer orientation, whether or not the system has a keyboard, 492 framebuffer orientation, whether or not the system has a keyboard,
492 the positioning of the keyboard in relation to the screen, and 493 the positioning of the keyboard in relation to the screen, and
493 screen resolution. 494 screen resolution.
494 </para> 495 </para>
495 <para> 496 <para>
496 Sane defaults should be used in most cases, but if customisation is 497 Reasonable defaults are used in most cases, but if customization is
497 necessary you need to create a <filename>machconfig</filename> file 498 necessary you need to create a <filename>machconfig</filename> file
498 under <filename>meta/packages/formfactor/files/MACHINENAME/</filename> 499 under <filename>meta/packages/formfactor/files/MACHINENAME/</filename>,
499 where <literal>MACHINENAME</literal> is the name for which this infomation 500 where <literal>MACHINENAME</literal> is the name for which this infomation
500 applies. For information about the settings available and the defaults, please see 501 applies.
501 <filename>meta/packages/formfactor/files/config</filename>. Below is one 502 For information about the settings available and the defaults, see
502 example for qemuarm: 503 <filename>meta/packages/formfactor/files/config</filename>.
503 </para> 504 Following is an example for qemuarm:
504 <programlisting> 505 </para>
506 <programlisting>
505HAVE_TOUCHSCREEN=1 507HAVE_TOUCHSCREEN=1
506HAVE_KEYBOARD=1 508HAVE_KEYBOARD=1
507 509
@@ -512,45 +514,44 @@ DISPLAY_ORIENTATION=0
512#DISPLAY_BPP=16 514#DISPLAY_BPP=16
513DISPLAY_DPI=150 515DISPLAY_DPI=150
514DISPLAY_SUBPIXEL_ORDER=vrgb 516DISPLAY_SUBPIXEL_ORDER=vrgb
515 </programlisting> 517 </programlisting>
518 </section>
516 </section> 519 </section>
517</section>
518 520
519<section id='usingpoky-changes'> 521 <section id="usingpoky-changes">
520 <title>Making and Maintaining Changes</title> 522 <title>Making and Maintaining Changes</title>
521
522 <para> 523 <para>
523 We recognise that people will want to extend/configure/optimise Poky for 524 Because Poky offers extreme configurability and fliexibility, we recognize that people will want
524 their specific uses, especially due to the extreme configurability and 525 to extend, configure or optimise Poky for their specific uses.
525 flexibility Poky offers. To ensure ease of keeping pace with future 526 To best keep pace with future Poky changes we recommend you make controlled changes to Poky.
526 changes in Poky we recommend making changes to Poky in a controlled way.
527 </para> 527 </para>
528 <para> 528 <para>
529 Poky supports the idea of <link 529 Poky supports the idea of <link linkend='usingpoky-changes-layers'>"layers"</link>.
530 linkend='usingpoky-changes-layers'>"layers"</link> which when used 530 If you use layers properly you can ease future upgrades and allow segregation
531 properly can massively ease future upgrades and allow segregation 531 between the Poky core and a given developer's changes.
532 between the Poky core and a given developer's changes. Some other advice on 532 The following section provides more advice on managing changes to Poky.
533 managing changes to Poky is also given in the following section.
534 </para> 533 </para>
535 534
536 <section id="usingpoky-changes-layers"> 535 <section id="usingpoky-changes-layers">
537 <title>Bitbake Layers</title> 536 <title>Bitbake Layers</title>
538
539 <para> 537 <para>
540 Often, people want to extend Poky either through adding packages 538 Often, people want to extend Poky either by adding packages
541 or overriding files contained within Poky to add their own 539 or by overriding files contained within Poky to add their own
542 functionality. Bitbake has a powerful mechanism called 540 functionality.
543 layers which provides a way to handle this extension in a fully 541 Bitbake has a powerful mechanism called
542 "layers", which provides a way to handle this extension in a fully
544 supported and non-invasive fashion. 543 supported and non-invasive fashion.
545 </para> 544 </para>
546
547 <para> 545 <para>
548 The Poky tree includes several additional layers which demonstrate 546 The Poky tree includes several additional layers such as meta-emenlow and meta-extras
549 this functionality, such as meta-emenlow and meta-extras. 547 that demonstrate this functionality.
550 The meta-emenlow layer is an example layer enabled by default. The meta-extras 548 The meta-emenlow layer is an example layer that by default is enabled.
551 repostory is not enabled by default but enabling any layer is as easy as adding 549 However, the meta-extras repostory is not enabled by default.
552 the layers path to the BBLAYERS variable in your bblayers.conf. this is how 550 It is easy though to enable any layer.
553 meta-extras are enabled in Poky builds: 551 You simply add the layer's path to the
552 <glossterm><link linkend='var-BBLAYERS'>BBLAYERS</link></glossterm> variable in your
553 <filename>bblayers.conf</filename> file.
554 The following example shows how to enable meta-extras in the Poky build:
554 </para> 555 </para>
555 <para> 556 <para>
556 <literallayout class='monospaced'>LCONF_VERSION = "1" 557 <literallayout class='monospaced'>LCONF_VERSION = "1"
@@ -565,15 +566,14 @@ BBLAYERS = " \
565 </para> 566 </para>
566 567
567 <para> 568 <para>
568 Bitbake parses the conf/layer.conf of each of the layers in BBLAYERS 569 Bitbake parses each <filename>conf/layer.conf</filename> file for each layer in BBLAYERS
569 to add the recipes, classes and configuration contained within the layer to Poky. 570 and adds the recipes, classes and configuration contained within the layer to Poky.
570 To create your own layer, independent of the main Poky repository, 571 To create your own layer, independent of the main Poky repository,
571 you need only create a directory with a conf/layer.conf file and 572 simply create a directory with a <filename>conf/layer.conf</filename> file and
572 add the directory to your bblayers.conf. 573 add the directory to your <filename>bblayers.conf</filename> file.
573 </para> 574 </para>
574
575 <para> 575 <para>
576 The meta-emenlow/conf/layer.conf demonstrates the required syntax: 576 The <filename>meta-emenlow/conf/layer.conf</filename> file demonstrates the required syntax:
577 <literallayout class='monospaced'># We have a conf and classes directory, add to BBPATH 577 <literallayout class='monospaced'># We have a conf and classes directory, add to BBPATH
578BBPATH := "${BBPATH}:${LAYERDIR}" 578BBPATH := "${BBPATH}:${LAYERDIR}"
579 579
@@ -586,66 +586,74 @@ BBFILE_PATTERN_emenlow := "^${LAYERDIR}/"
586BBFILE_PRIORITY_emenlow = "6" 586BBFILE_PRIORITY_emenlow = "6"
587 </literallayout> 587 </literallayout>
588 </para> 588 </para>
589
590 <para> 589 <para>
591 As can be seen, the layers recipes are added to 590 In the previous example, the recipes for the layers are added to
592 <glossterm> <link linkend='var-BBFILES'>BBFILES</link></glossterm>. The 591 <glossterm> <link linkend='var-BBFILES'>BBFILES</link></glossterm>.
593 BBFILE_COLLECTIONS variable is then appended to with the 592 The <glossterm><link linkend='var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link></glossterm>
594 layer name. The BBFILE_PATTERN variable is immediately expanded 593 variable is then appended with the layer name.
595 with a regular expression used to match files from BBFILES into 594 The <glossterm><link linkend='var-BBFILE_PATTERN'>BBFILE_PATTERN</link></glossterm> variable
595 immediately expands with a regular expression used to match files from BBFILES into
596 a particular layer, in this case by using the base pathname. 596 a particular layer, in this case by using the base pathname.
597 The BBFILE_PRIORITY variable then assigns different 597 The <glossterm><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></glossterm> variable
598 priorities to the files in different layers. This is useful 598 then assigns different priorities to the files in different layers.
599 in situations where the same package might appear in multiple 599 This technique useful in situations where the same package might appear in multiple
600 layers and allows you to choose which layer should 'win'. 600 layers and allows you to choose what layer should take precedence.
601 Note the use of <glossterm><link linkend='var-LAYERDIR'> 601 </para>
602 LAYERDIR</link></glossterm> with the immediate expansion operator. 602 <para>
603 <glossterm><link linkend='var-LAYERDIR'>LAYERDIR</link></glossterm> 603 Note the use of the <glossterm><link linkend='var-LAYERDIR'>LAYERDIR</link></glossterm>
604 expands to the directory of the current layer and 604 variable with the immediate expansion operator.
605 requires use of the immediate expansion operator so that Bitbake 605 The LAYERDIR variable expands to the directory of the current layer and
606 does not lazily expand the variable when it's parsing a 606 requires the immediate expansion operator so that Bitbake does not wait to expand the variable
607 different directory. 607 when it's parsing a different directory.
608 </para> 608 </para>
609 609 <para>
610 <para> 610 Bitbake can locate where other bbclass and configuration files are applied through
611 Additional bbclass and configuration files can be locationed by 611 the <glossterm><link linkend='var-BBPATH'>BBPATH</link></glossterm>
612 bitbake through the addition to the BBPATH 612 environment variable.
613 environment variable. In this case, the first file with the 613 For these cases, Bitake uses the first file with the matching name found in BBPATH.
614 matching name found in BBPATH is the one that is used, just 614 This is similar to the way the PATH variable is used for binaries.
615 like the PATH variable for binaries. It is therefore recommended 615 We recommend, therefore, that you use unique bbclass and configuration file names in your
616 that you use unique bbclass and configuration file names in your
617 custom layer. 616 custom layer.
618 </para> 617 </para>
619
620 <para> 618 <para>
621 The recommended approach for custom layers is to store them in a 619 We also recommend the following:
622 git repository of the format meta-prvt-XXXX and have this repository 620 <itemizedlist>
623 cloned alongside the other meta directories in the Poky tree. 621 <listitem><para>Store custom layers in a git repository that uses the
624 This way you can keep your Poky tree and it's configuration entirely 622 meta-prvt-XXXX format.</para></listitem>
623 <listitem><para>Clone the repository alongside other meta directories in the Poky
624 tree.</para></listitem>
625 </itemizedlist>
626 Following these recommendations keeps your Poky tree and its configuration entirely
625 inside POKYBASE. 627 inside POKYBASE.
626 </para> 628 </para>
627 </section> 629 </section>
628 630
629 <section id='usingpoky-changes-commits'> 631 <section id="usingpoky-changes-commits">
630 <title>Committing Changes</title> 632 <title>Committing Changes</title>
631
632 <para> 633 <para>
633 Modifications to Poky are often managed under some kind of source 634 Modifications to Poky are often managed under some kind of source
634 revision control system. The policy for committing to such systems 635 revision control system.
635 is important as some simple policy can significantly improve 636 Because some simple practices can significantly improve usability, policy for committing changes
636 usability. The tips below are based on the policy followed for the 637 is important.
637 Poky core. 638 Following are suggestions for committing changes to the Poky core:
638 </para> 639 </para>
639
640 <para> 640 <para>
641 It helps to use a consistent style for commit messages when committing 641 It helps to use a consistent documentation style when committing changes.
642 changes. We've found a style where the first line of a commit message 642 We have found the following style works well.
643 summarises the change and starts with the name of any package affected 643 <itemizedlist>
644 work well. Not all changes are to specific packages so the prefix could 644 <listitem><para>The first line of the commit summarizes the change and begins with the
645 also be a machine name or class name instead. If a change needs a longer 645 name of the affected package or packages.
646 description this should follow the summary: 646 However, not all changes apply to specific packages.
647 Consequently, the prefix could also be a machine name or class name for
648 example.</para></listitem>
649 <listitem><para>The second part of the commit (if needed) is a longer more detailed
650 description of the changes. Placing a blank line between the first and second parts
651 helps with readability.</para></listitem>
652 </itemizedlist>
653 </para>
654 <para>
655 Following is an example commit:
647 </para> 656 </para>
648
649 <literallayout class='monospaced'> 657 <literallayout class='monospaced'>
650 bitbake/data.py: Add emit_func() and generate_dependencies() functions 658 bitbake/data.py: Add emit_func() and generate_dependencies() functions
651 659
@@ -657,111 +665,121 @@ BBFILE_PRIORITY_emenlow = "6"
657 </literallayout> 665 </literallayout>
658 666
659 <para> 667 <para>
660 Any commit should be self contained in that it should leave the 668 All commits should be self-contained such that they leave the
661 metadata in a consistent state, buildable before and after the 669 metadata in a consistent state that builds both before and after the
662 commit. This helps ensure the autobuilder test results are valid 670 commit is made.
663 but is good practice regardless. 671 Besides being a good policy to follow, this helps ensure the autobuilder test results
672 are valid.
664 </para> 673 </para>
665 </section> 674 </section>
666 675
667 <section id='usingpoky-changes-prbump'> 676 <section id="usingpoky-changes-prbump">
668 <title>Package Revision Incrementing</title> 677 <title>Package Revision Incrementing</title>
669
670 <para> 678 <para>
671 If a committed change will result in changing the package output 679 If a committed change results in changing the package output
672 then the value of the <glossterm><link linkend='var-PR'>PR</link> 680 then the value of the <glossterm><link linkend='var-PR'>PR</link>
673 </glossterm> variable needs to be increased (commonly referred to 681 </glossterm> variable needs to be increased ('bumped') as part of that commit.
674 as 'bumped') as part of that commit. Only integer values are used 682 This means that for new recipes you be sure to add the PR variable and set its initial value
675 and <glossterm><link linkend='var-PR'>PR</link></glossterm> = 683 equal to "r0".
676 "r0" should be added into new recipes as, while this is the 684 Not initially defining PR makes makes it easy to miss when you bump a package.
677 default value, not having the variable defined in a recipe makes 685 Note that you can only use integer values for the PR variable.
678 it easy to miss incrementing it when updating the recipe. 686 </para>
679 When upgrading the version of a package (<glossterm><link 687 <para>
680 linkend='var-PV'>PV</link></glossterm>), the <glossterm><link 688 When upgrading the version of a package the (<glossterm><link
681 linkend='var-PR'>PR</link></glossterm> variable should be reset to "r0". 689 linkend='var-PV'>PV</link></glossterm>) and PR variables should be reset to "r0".
682 </para> 690 </para>
683
684 <para> 691 <para>
685 The aim is that the package version will only ever increase. If 692 Usually a package version only increases.
686 for some reason <glossterm><link linkend='var-PV'>PV</link></glossterm> 693 However, if for some reason PV changes but does not increase, you can increase the
687 will change and but not increase, the <glossterm><link 694 <glossterm><link linkend='var-PE'>PE</link></glossterm> variable (Package Epoch).
688 linkend='var-PE'>PE</link></glossterm> (Package Epoch) can 695 The PE variable defaults to '0'.
689 be increased (it defaults to '0'). The version numbers aim to 696 </para>
690 follow the <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'> 697 <para>
691 Debian Version Field Policy Guidelines</ulink> which define how 698 Version numbering strives to follow the
692 versions are compared and hence what "increasing" means. 699 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
700 Debian Version Field Policy Guidelines</ulink>.
701 These guidelines define how versions are compared and what "increasing" a version means.
693 </para> 702 </para>
694
695 <para> 703 <para>
696 There are two reasons for doing this, the first is to ensure that 704 There are two reasons for following these guidelines.
697 when a developer updates and rebuilds, they get all the changes to 705 First, to ensure that when a developer updates and rebuilds, they get all the changes to
698 the repository and don't have to remember to rebuild any sections. 706 the repository and don't have to remember to rebuild any sections.
699 The second is to ensure that target users are able to upgrade their 707 Second, to ensure that target users are able to upgrade their
700 devices via their package manager such as with the <command> 708 devices using package manager commands such as <filename>
701 opkg upgrade</command> commands (or similar for 709 opkg upgrade</filename> (or similar commands for dpkg/apt or rpm-based systems).
702 dpkg/apt or rpm based systems). The aim is to ensure Poky has 710 </para>
703 upgradable packages in all cases. 711 <para>
712 The goal is to ensure Poky has upgradable packages in all cases.
704 </para> 713 </para>
705 </section> 714 </section>
706 <section id='usingpoky-changes-collaborate'>
707 <title>Using Poky in a Team Environment</title>
708 715
716 <section id="usingpoky-changes-collaborate">
717 <title>Using Poky in a Team Environment</title>
709 <para> 718 <para>
710 It may not be immediately clear how Poky can work in a team environment, 719 It may not be immediately clear how you can use Poky in a team environment,
711 or scale to a large team of developers. The specifics of any situation 720 or scale it for a large team of developers.
712 will determine the best solution and poky offers immense flexibility in 721 The specifics of any situation determine the best solution.
713 that aspect but there are some practises that experience has shown to work 722 Granted that Poky offers immense flexibility regarding this, practices do exist
714 well. 723 that experience has shown work well.
715 </para> 724 </para>
716
717 <para> 725 <para>
718 The core component of any development effort with Poky is often an 726 The core component of any development effort with Poky is often an
719 automated build testing framework and image generation process. This 727 automated build testing framework and an image generation process.
720 can be used to check that the metadata is buildable, highlight when 728 You can use these core components to check that the metadata is buildable,
721 commits break the builds and provide up to date images allowing people 729 highlight when commits break the builds, and provide up-to-date images that
722 to test the end result and use them as a base platform for further 730 allow people to test the end result and use it as a base platform for further
723 development. Experience shows that buildbot is a good fit for this role 731 development.
724 and that it works well to configure it to make two types of build - 732 Experience shows that buildbot is a good fit for this role.
725 incremental builds and 'from scratch'/full builds. The incremental builds 733 What works well is to configure buildbot to make two types of builds:
726 can be tied to a commit hook which triggers them each time a commit is 734 incremental and full (from scratch).
727 made to the metadata and are a useful acid test of whether a given commit 735 See <ulink url='http://autobuilder.pokylinux.org:8010'>poky autobuilder</ulink>
728 breaks the build in some serious way. They catch lots of simple errors 736 for an example implementation that uses buildbot.
729 and whilst they won't catch 100% of failures, the tests are fast so 737 </para>
730 developers can get feedback on their changes quickly. The full builds 738 <para>
731 are builds that build everything from the ground up and test everything. 739 You can tie incremental builds to a commit hook that triggers the build
732 They usually happen at preset times such as at night when the machine 740 each time a commit is made to the metadata.
733 load isn't high from the incremental builds. 741 This practice results in useful acid tests that determine whether a given commit
734 <ulink url='http://autobuilder.pokylinux.org:8010'>poky autobuilder</ulink> 742 breaks the build in some serious way.
735 is an example implementation with buildbot. 743 Associating a build to a commit can catch a lot of simple errors.
736 </para> 744 Furthermore, the tests are fast so developers can get quick feedback on changes.
737 745 </para>
738 <para> 746 <para>
739 Most teams have pieces of software undergoing active development. It is of 747 Full builds build and test everything from the ground up.
740 significant benefit to put these under control of a source control system 748 They usually happen at preset times like during the night when the machine
741 compatible with Poky such as git or svn. The autobuilder can then be set to 749 load is low.
742 pull the latest revisions of these packages so the latest commits get tested 750 </para>
743 by the builds allowing any issues to be highlighted quickly. Poky easily 751 <para>
744 supports configurations where there is both a stable known good revision 752 Most teams have many pieces of software undergoing active development at any given time.
745 and a floating revision to test. Poky can also only take changes from specific 753 You can derive large benefits by putting these pieces under the control of a source
746 source control branches giving another way it can be used to track/test only 754 control system that is compatible with Poky (i.e. git or svn).
747 specified changes. 755 You can then set the autobuilder to pull the latest revisions of the packages
748 </para> 756 and test the latest commits by the builds.
749 <para> 757 This practice quickly highlights issues.
750 Perhaps the hardest part of setting this up is the policy that surrounds 758 Poky easily supports testing configurations that use both a stable known good revision
751 the different source control systems, be them software projects or the Poky 759 and a floating revision.
752 metadata itself. The circumstances will be different in each case but this is 760 Poky can also take just the changes from specific source control branches.
753 one of Poky's advantages - the system itself doesn't force any particular policy 761 This capability allows you to track and test specific changes.
754 unlike a lot of build systems, allowing the best policy to be chosen for the 762 </para>
755 circumstances. 763 <para>
764 Perhaps the hardest part of setting this up is defining the software project or
765 Poky metadata policies that surround the different source control systems.
766 Of course circumstances will be different in each case.
767 However, this situation reveals one of Poky's advantages - the system itself does not
768 force any particular policy on users, unlike a lot of build systems.
769 The system allows the best policy to be chosen for the given circumstances.
756 </para> 770 </para>
757 </section> 771 </section>
758 772
759 <section id='usingpoky-changes-updatingimages'> 773 <section id="usingpoky-changes-updatingimages">
760 <title>Updating Existing Images</title> 774 <title>Updating Existing Images</title>
761
762 <para> 775 <para>
763 Often, rather than reflashing a new image you might wish to install updated 776 Often, rather than reflashing a new image you might wish to install updated
764 packages into an existing running system. This can be done by sharing the <filename class="directory">tmp/deploy/ipk/</filename> directory through a web server and then on the device, changing <filename>/etc/opkg/base-feeds.conf</filename> to point at this server, for example by adding: 777 packages into an existing running system.
778 You can do this by first sharing the
779 <filename class="directory">tmp/deploy/ipk/</filename> directory
780 through a web server and then by changing <filename>/etc/opkg/base-feeds.conf</filename>
781 to point at the shared server.
782 Following is an example:
765 </para> 783 </para>
766 <literallayout class='monospaced'> 784 <literallayout class='monospaced'>
767src/gz all http://www.mysite.com/somedir/deploy/ipk/all 785src/gz all http://www.mysite.com/somedir/deploy/ipk/all
@@ -770,41 +788,33 @@ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard</literal
770 </section> 788 </section>
771 </section> 789 </section>
772 790
773 <section id='usingpoky-modifing-packages'> 791 <section id="usingpoky-modifing-packages">
774 <title>Modifying Package Source Code</title> 792 <title>Modifying Package Source Code</title>
775
776 <para> 793 <para>
777 Poky is usually used to build software rather than modifying 794 Although Poky is usually used to build software, you can use it to modify software.
778 it. However, there are ways Poky can be used to modify software.
779 </para> 795 </para>
780
781 <para> 796 <para>
782 During building, the sources are available in <glossterm><link 797 During building, source is available in the
783 linkend='var-WORKDIR'>WORKDIR</link></glossterm> directory. 798 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> directory.
784 Where exactly this is depends on the type of package and the 799 The actual location depends on the type of package and the architecture of the target device.
785 architecture of target device. For a standard recipe not 800 For a standard recipe not related to
786 related to <glossterm><link 801 <glossterm><link linkend='var-MACHINE'>MACHINE</link></glossterm> the location is
787 linkend='var-MACHINE'>MACHINE</link></glossterm> it will be
788 <filename>tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/</filename>. 802 <filename>tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/</filename>.
789 Target device dependent packages use <glossterm><link 803 For target device-dependent packages you should use the MACHINE variable instead of
790 linkend='var-MACHINE'>MACHINE 804 <glossterm><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></glossterm>
791 </link></glossterm>
792 instead of <glossterm><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH
793 </link></glossterm>
794 in the directory name. 805 in the directory name.
795 </para> 806 </para>
796
797 <tip> 807 <tip>
798 <para> 808 <para>
799 Check the package recipe sets the <glossterm><link 809 Be sure the package recipe sets the
800 linkend='var-S'>S</link></glossterm> variable to something 810 <glossterm><link linkend='var-S'>S</link></glossterm> variable to something
801 other than standard <filename>WORKDIR/PN-PV/</filename> value. 811 other than standard <filename>WORKDIR/PN-PV/</filename> value.
802 </para> 812 </para>
803 </tip> 813 </tip>
804 <para> 814 <para>
805 After building a package, a user can modify the package source code 815 After building a package, you can modify the package source code without problems.
806 without problem. The easiest way to test changes is by calling the 816 The easiest way to test your changes is by calling the "compile" task as shown in the
807 "compile" task: 817 following example:
808 </para> 818 </para>
809 819
810 <programlisting> 820 <programlisting>
@@ -812,184 +822,179 @@ bitbake -c compile -f NAME_OF_PACKAGE
812 </programlisting> 822 </programlisting>
813 823
814 <para> 824 <para>
815 "-f" or "--force" is used to force re-execution of the specified task. 825 The "-f" or "--force" option forces re-execution of the specified task.
816 Other tasks may also be called this way. But note that all the modifications 826 You can call other tasks this way as well.
817 in <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> 827 But note that all the modifications in
818 are gone once you executes "-c clean" for a package. 828 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>
829 are gone once you execute "-c clean" for a package.
819 </para> 830 </para>
820 831
821 <section id='usingpoky-modifying-packages-quilt'> 832 <section id="usingpoky-modifying-packages-quilt">
822 <title>Modifying Package Source Code with quilt</title> 833 <title>Modifying Package Source Code with quilt</title>
823
824 <para> 834 <para>
825 By default Poky uses <ulink 835 By default Poky uses <ulink url='http://savannah.nongnu.org/projects/quilt'>quilt</ulink>
826 url='http://savannah.nongnu.org/projects/quilt'>quilt</ulink> 836 to manage patches in the <filename>do_patch</filename> task.
827 to manage patches in <function>do_patch</function> task. 837 This is a powerful tool that you can use to track all modifications to package sources.
828 It is a powerful tool which can be used to track all
829 modifications done to package sources.
830 </para> 838 </para>
831
832 <para> 839 <para>
833 Before modifying source code it is important to 840 Before modifying source code, it is important to notify quilt so it can track the changes
834 notify quilt so it will track changes into new patch 841 into the new patch file:
835 file: 842
836 <programlisting> 843 <programlisting>
837quilt new NAME-OF-PATCH.patch 844quilt new NAME-OF-PATCH.patch
838 </programlisting> 845 </programlisting>
839 846
840 Then add all files which will be modified into that 847 After notifying quilt, add all modified files into that patch:
841 patch:
842 <programlisting> 848 <programlisting>
843quilt add file1 file2 file3 849quilt add file1 file2 file3
844 </programlisting> 850 </programlisting>
845 851
846 Now start editing. At the end quilt needs to be used 852 You can now start editing.
847 to generate final patch which will contain all 853 Once you are done editing, you need to use quilt to generate the final patch that
848 modifications: 854 will contain all your modifications.
849 <programlisting> 855 <programlisting>
850quilt refresh 856quilt refresh
851 </programlisting> 857 </programlisting>
852 858
853 The resulting patch file can be found in the 859 You can find the resulting patch file in the
854 <filename class="directory">patches/</filename> subdirectory of the source 860 <filename class="directory">patches/</filename> subdirectory of the source
855 (<glossterm><link linkend='var-S'>S</link></glossterm>) directory. For future builds it 861 (<glossterm><link linkend='var-S'>S</link></glossterm>) directory.
856 should be copied into 862 For future builds you should copy the patch into Poky metadata and add it into the
857 Poky metadata and added into <glossterm><link 863 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> of a recipe.
858 linkend='var-SRC_URI'>SRC_URI</link></glossterm> of a recipe: 864 Here is an example:
859 <programlisting> 865 <programlisting>
860SRC_URI += "file://NAME-OF-PATCH.patch" 866SRC_URI += "file://NAME-OF-PATCH.patch"
861 </programlisting> 867 </programlisting>
862 868 Finally, don't forget to 'bump' the
863 This also requires a bump of <glossterm><link 869 <glossterm><link linkend='var-PR'>PR</link></glossterm> value in the same recipe.
864 linkend='var-PR'>PR</link></glossterm> value in the same recipe as we changed resulting packages. 870 The resulting packages have changed.
865 </para> 871 </para>
866
867 </section> 872 </section>
868 873
869 </section> 874 </section>
870 <section id='usingpoky-configuring-LIC_FILES_CHKSUM'> 875
871 <title>Track license change</title> 876 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
877 <title>Track License Change</title>
872 <para> 878 <para>
873 The license of one upstream project may change in the future, and Poky provides 879 The license of an upstream project might change in the future.
874 one mechanism to track such license change - <glossterm> 880 To address this situation, Poky uses the
875 <link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> variable. 881 <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> variable
882 to track license changes.
876 </para> 883 </para>
877 884
878 <section id='usingpoky-specifying-LIC_FILES_CHKSUM'> 885 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
879 <title>Specifying the LIC_FILES_CHKSUM variable </title> 886 <title>Specifying the LIC_FILES_CHKSUM Variable </title>
880 887 <para>
888 The <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm>
889 variable contains checksums of the license text in the recipe source code.
890 Poky uses this to track changes in the license text of the source code files.
891 Following is an example of LIC_FILES_CHKSUM:
892 </para>
881 <programlisting> 893 <programlisting>
882LIC_FILES_CHKSUM = "file://COPYING; md5=xxxx \ 894LIC_FILES_CHKSUM = "file://COPYING; md5=xxxx \
883 file://licfile1.txt; beginline=5; endline=29;md5=yyyy \ 895 file://licfile1.txt; beginline=5; endline=29;md5=yyyy \
884 file://licfile2.txt; endline=50;md5=zzzz \ 896 file://licfile2.txt; endline=50;md5=zzzz \
885 ..." 897 ..."
886 </programlisting> 898 </programlisting>
887
888 <para> 899 <para>
889 <glossterm><link linkend='var-S'>S</link></glossterm> is the default directory 900 Poky uses the <glossterm><link linkend='var-S'>S</link></glossterm> variable as the
890 for searching files listed in <glossterm><link linkend='var-LIC_FILES_CHKSUM'> 901 default directory used when searching files listed in LIC_FILES_CHKSUM.
891 LIC_FILES_CHKSUM</link></glossterm>. Relative path could be used too: 902 The previous example employs the default directory.
903 </para>
904 <para>
905 You can also use relative paths as shown in the following example:
892 </para> 906 </para>
893
894 <programlisting> 907 <programlisting>
895LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ 908LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
896 md5=bb14ed3c4cda583abc85401304b5cd4e" 909 md5=bb14ed3c4cda583abc85401304b5cd4e"
897LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" 910LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
898 </programlisting> 911 </programlisting>
899
900 <para> 912 <para>
901 The first line locates a file in <glossterm><link linkend='var-S'> 913 In this example the first line locates a file in
902 S</link></glossterm>/src/ls.c, and the second line refers to a file in 914 <glossterm><link linkend='var-S'>S</link></glossterm><filename>/src/ls.c</filename>.
903 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>, which is the parent 915 The second line refers to a file in
904 of <glossterm><link linkend='var-S'>S</link></glossterm> 916 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>, which is the parent
917 of <glossterm><link linkend='var-S'>S</link></glossterm>.
905 </para> 918 </para>
906
907 </section> 919 </section>
908 920
909 <section id='usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax'> 921 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
910 <title>Explanation of syntax</title> 922 <title>Explanation of Syntax</title>
911
912 <para> 923 <para>
913 This parameter lists all the important files containing the text 924 As mentioned in the previous section the LIC_FILES_CHKSUM variable lists all the
914of licenses for the 925 important files that contain the license text for the source code.
915source code. It is also possible to specify on which line the license text 926 Using this variable you can specify the line on which the license text starts and ends
916starts and on which line it ends within that file using the "beginline" and 927 by supplyiing "beginline" and "endline" parameters.
917"endline" parameters. If the "beginline" parameter is not specified then license 928 If you do not use the "beginline" parameter then it is assumed that the text begins on the
918text begins from the 1st line is assumed. Similarly if "endline" parameter is 929 first line of the file.
919not specified then the license text ends at the last line in the file is 930 Similarly, if you do not use the "endline" parameter it is assumed that the license text
920assumed. So if a file contains only licensing information, then there is no need 931 ends as the last line of the file.
921to specify "beginline" and "endline" parameters.
922 </para> 932 </para>
923 <para> 933 <para>
924The "md5" parameter stores the md5 checksum of the license text. So if 934 The "md5" parameter stores the md5 checksum of the license text.
925the license text changes in any way from a file, then its md5 sum will differ and will not 935 If the license text changes in any way as compared to this parameter
926match with the previously stored md5 checksum. This mismatch will trigger build 936 then a mis-match occurs.
927failure, notifying developer about the license text md5 mismatch, and allowing 937 This mismatch triggers a build failure and notifies the developer.
928the developer to review the license text changes. Also note that if md5 checksum 938 Notification allows the developer to review and address the license text changes.
929is not matched while building, the correct md5 checksum is printed in the build 939 Also note that if a mis-match occurs during the build, the correct md5
930log which can be easily copied to .bb file. 940 checksum is placed in the build log, which can be easily copied to a .bb file.
931 </para> 941 </para>
932 <para> 942 <para>
933There is no limit on how many files can be specified on this parameter. But generally every 943 There is no limit to how many files you can specify using the LIC_FILES_CHKSUM variable.
934project would need specifying of just one or two files for license tracking. 944 Generally, however, every project requires a few specifications for license tracking.
935Many projects would have a "COPYING" file which will store all the 945 Many projects have a "COPYING" file that stores the license information for all the source
936license information for all the source code files. If the "COPYING" file 946 code files.
937is valid then tracking only that file would be enough. 947 This practice allow you to just track the "COPYING" file as long as it is kept up to date.
938 </para> 948 </para>
939 <tip> 949 <tip>
940 <para> 950 If you specify an empty or invalid "md5" parameter, bitback returns an md5 mis-match
9411. If you specify empty or invalid "md5" parameter; then while building 951 error and displays the correct "md5" parameter value during the build. The correct parameter
942the package, bitbake will give md5 not matched error, and also show the correct 952 is also captured in the build log.
943"md5" parameter value both on the screen and in the build log 953 </tip>
944 </para> 954 <tip>
945 <para> 955 If the whole file contains only license text, you do not need to use the "beginline" and
9462. If the whole file contains only license text, then there is no need to 956 "endline" parameters.
947specify "beginline" and "endline" parameters.
948 </para>
949 </tip> 957 </tip>
950 </section> 958 </section>
951 </section> 959 </section>
952 <section id='usingpoky-configuring-DISTRO_PN_ALIAS'> 960
953 <title>Handle package name alias</title> 961 <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
962 <title>Handling Package Name Alias</title>
954 <para> 963 <para>
955Poky implements a distro_check task which automatically connects to major distributions 964 Sometimes a package name you are using might exist under an alias or as a similarly named
956and checks whether they contains same package. Sometimes the same package has different 965 package in a different distribution.
957names in different distributions, which results in a mismatch from distro_check task 966 Poky implements a distro_check task that automatically connects to major distributions
958This can be solved by defining per distro recipe name alias - 967 and checks for these situations.
959<glossterm><link linkend='var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</link></glossterm> 968 If the package exists under a different name in a different distribution you get a
969 distro_check mismatch.
970 You can resolve this problem by defining a per-distro recipe name alias using the
971 <glossterm><link linkend='var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</link></glossterm> variable.
960 </para> 972 </para>
961 973
962 <section id='usingpoky-specifying-DISTRO_PN_ALIAS'> 974 <section id="usingpoky-specifying-DISTRO_PN_ALIAS">
963 <title>Specifying the DISTRO_PN_ALIAS variable </title> 975 <title>Specifying the DISTRO_PN_ALIAS Variable</title>
964 976 <para>
977 Following is an example that shows how you specify the DISTRO_PN_ALIAS variable:
965 <programlisting> 978 <programlisting>
966DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ 979DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
967 distro2=package_name_alias2 \ 980 distro2=package_name_alias2 \
968 distro3=package_name_alias3 \ 981 distro3=package_name_alias3 \
969 ..." 982 ..."
970 </programlisting> 983 </programlisting>
984 </para>
971 <para> 985 <para>
972Use space as the delimiter if there're multiple distro aliases 986 If you have more than one distribution alias separate them with a space.
987 Note that Poky currently automatically checks the Fedora, OpenSuSE, Debian, Ubuntu,
988 and Mandriva distributions for source package recipes without having to specify them
989 using the DISTRO_PN_ALIAS variable.
990 For example, the following command generates a report that lists the Linux distributions
991 that include the sources for each of the Poky recipes.
992 <literallayout class='monospaced'>
993 $ bitbake world -f -c distro_check
994 </literallayout>
995 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
996 file.
973 </para> 997 </para>
974 <tip>
975 <para>
976The current code can check if the src package for a recipe exists in the latest
977releases of these distributions automatically.
978 </para>
979 <programlisting>
980Fedora, OpenSuSE, Debian, Ubuntu, Mandriva
981 </programlisting>
982 <para>
983For example, this command will generate a report, listing which linux distros include the
984sources for each of the poky recipe.
985 </para>
986 <programlisting>
987bitbake world -f -c distro_check
988 </programlisting>
989 <para>
990The results will be stored in the build/tmp/log/distro_check-${DATETIME}.results file.
991 </para>
992 </tip>
993 </section> 998 </section>
994 </section> 999 </section>
995</chapter> 1000</chapter>