diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2018-02-01 10:30:31 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-02-14 15:25:31 +0000 |
commit | 8d320536dcda978a43693e1874c32d9d95e42b5e (patch) | |
tree | 4a92d9ea3daebc99c22b233cdf4ab1491655fc79 /documentation/dev-manual | |
parent | 72be05b9f5918a944db988da5e81c4833be37020 (diff) | |
download | poky-8d320536dcda978a43693e1874c32d9d95e42b5e.tar.gz |
dev-manual, getting-started: Moved the BB syntax section
This section on BitBake syntax appeared in the Getting Started
manual. I decided that it should live with the section on
writing a new recipe.
(From yocto-docs rev: 8d83ce3e11405b2f12f27cdd117a19c4af52146a)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 328 |
1 files changed, 326 insertions, 2 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 167d107155..dbbe67657d 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml | |||
@@ -1507,8 +1507,8 @@ | |||
1507 | </itemizedlist> | 1507 | </itemizedlist> |
1508 | <note> | 1508 | <note> |
1509 | For information on recipe syntax, see the | 1509 | For information on recipe syntax, see the |
1510 | "<ulink url='&YOCTO_DOCS_GS_URL;#recipe-syntax'>Recipe Syntax</ulink>" | 1510 | "<link linkend='recipe-syntax'>Recipe Syntax</link>" |
1511 | section in the Getting Started With Yocto Project Manual. | 1511 | section. |
1512 | </note> | 1512 | </note> |
1513 | </para> | 1513 | </para> |
1514 | 1514 | ||
@@ -3505,6 +3505,330 @@ | |||
3505 | style. | 3505 | style. |
3506 | </para> | 3506 | </para> |
3507 | </section> | 3507 | </section> |
3508 | |||
3509 | <section id='recipe-syntax'> | ||
3510 | <title>Recipe Syntax</title> | ||
3511 | |||
3512 | <para> | ||
3513 | Understanding recipe file syntax is important for writing | ||
3514 | recipes. | ||
3515 | The following list overviews the basic items that make up a | ||
3516 | BitBake recipe file. | ||
3517 | For more complete BitBake syntax descriptions, see the | ||
3518 | "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>" | ||
3519 | chapter of the BitBake User Manual. | ||
3520 | <itemizedlist> | ||
3521 | <listitem><para> | ||
3522 | <emphasis>Variable Assignments and Manipulations:</emphasis> | ||
3523 | Variable assignments allow a value to be assigned to a | ||
3524 | variable. | ||
3525 | The assignment can be static text or might include | ||
3526 | the contents of other variables. | ||
3527 | In addition to the assignment, appending and prepending | ||
3528 | operations are also supported.</para> | ||
3529 | |||
3530 | <para>The following example shows some of the ways | ||
3531 | you can use variables in recipes: | ||
3532 | <literallayout class='monospaced'> | ||
3533 | S = "${WORKDIR}/postfix-${PV}" | ||
3534 | CFLAGS += "-DNO_ASM" | ||
3535 | SRC_URI_append = " file://fixup.patch" | ||
3536 | </literallayout> | ||
3537 | </para></listitem> | ||
3538 | <listitem><para> | ||
3539 | <emphasis>Functions:</emphasis> | ||
3540 | Functions provide a series of actions to be performed. | ||
3541 | You usually use functions to override the default | ||
3542 | implementation of a task function or to complement | ||
3543 | a default function (i.e. append or prepend to an | ||
3544 | existing function). | ||
3545 | Standard functions use <filename>sh</filename> shell | ||
3546 | syntax, although access to OpenEmbedded variables and | ||
3547 | internal methods are also available.</para> | ||
3548 | |||
3549 | <para>The following is an example function from the | ||
3550 | <filename>sed</filename> recipe: | ||
3551 | <literallayout class='monospaced'> | ||
3552 | do_install () { | ||
3553 | autotools_do_install | ||
3554 | install -d ${D}${base_bindir} | ||
3555 | mv ${D}${bindir}/sed ${D}${base_bindir}/sed | ||
3556 | rmdir ${D}${bindir}/ | ||
3557 | } | ||
3558 | </literallayout> | ||
3559 | It is also possible to implement new functions that | ||
3560 | are called between existing tasks as long as the | ||
3561 | new functions are not replacing or complementing the | ||
3562 | default functions. | ||
3563 | You can implement functions in Python | ||
3564 | instead of shell. | ||
3565 | Both of these options are not seen in the majority of | ||
3566 | recipes. | ||
3567 | </para></listitem> | ||
3568 | <listitem><para><emphasis>Keywords:</emphasis> | ||
3569 | BitBake recipes use only a few keywords. | ||
3570 | You use keywords to include common | ||
3571 | functions (<filename>inherit</filename>), load parts | ||
3572 | of a recipe from other files | ||
3573 | (<filename>include</filename> and | ||
3574 | <filename>require</filename>) and export variables | ||
3575 | to the environment (<filename>export</filename>). | ||
3576 | </para> | ||
3577 | |||
3578 | <para>The following example shows the use of some of | ||
3579 | these keywords: | ||
3580 | <literallayout class='monospaced'> | ||
3581 | export POSTCONF = "${STAGING_BINDIR}/postconf" | ||
3582 | inherit autoconf | ||
3583 | require otherfile.inc | ||
3584 | </literallayout> | ||
3585 | </para></listitem> | ||
3586 | <listitem><para> | ||
3587 | <emphasis>Comments (#):</emphasis> | ||
3588 | Any lines that begin with the hash character | ||
3589 | (<filename>#</filename>) are treated as comment lines | ||
3590 | and are ignored: | ||
3591 | <literallayout class='monospaced'> | ||
3592 | # This is a comment | ||
3593 | </literallayout> | ||
3594 | </para></listitem> | ||
3595 | </itemizedlist> | ||
3596 | </para> | ||
3597 | |||
3598 | <para> | ||
3599 | This next list summarizes the most important and most commonly | ||
3600 | used parts of the recipe syntax. | ||
3601 | For more information on these parts of the syntax, you can | ||
3602 | reference the | ||
3603 | <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink> | ||
3604 | chapter in the BitBake User Manual. | ||
3605 | <itemizedlist> | ||
3606 | <listitem><para> | ||
3607 | <emphasis>Line Continuation (\):</emphasis> | ||
3608 | Use the backward slash (<filename>\</filename>) | ||
3609 | character to split a statement over multiple lines. | ||
3610 | Place the slash character at the end of the line that | ||
3611 | is to be continued on the next line: | ||
3612 | <literallayout class='monospaced'> | ||
3613 | VAR = "A really long \ | ||
3614 | line" | ||
3615 | </literallayout> | ||
3616 | <note> | ||
3617 | You cannot have any characters including spaces | ||
3618 | or tabs after the slash character. | ||
3619 | </note> | ||
3620 | </para></listitem> | ||
3621 | <listitem><para> | ||
3622 | <emphasis>Using Variables (${<replaceable>VARNAME</replaceable>}):</emphasis> | ||
3623 | Use the <filename>${<replaceable>VARNAME</replaceable>}</filename> | ||
3624 | syntax to access the contents of a variable: | ||
3625 | <literallayout class='monospaced'> | ||
3626 | SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" | ||
3627 | </literallayout> | ||
3628 | <note> | ||
3629 | It is important to understand that the value of a | ||
3630 | variable expressed in this form does not get | ||
3631 | substituted automatically. | ||
3632 | The expansion of these expressions happens | ||
3633 | on-demand later (e.g. usually when a function that | ||
3634 | makes reference to the variable executes). | ||
3635 | This behavior ensures that the values are most | ||
3636 | appropriate for the context in which they are | ||
3637 | finally used. | ||
3638 | On the rare occasion that you do need the variable | ||
3639 | expression to be expanded immediately, you can use | ||
3640 | the <filename>:=</filename> operator instead of | ||
3641 | <filename>=</filename> when you make the | ||
3642 | assignment, but this is not generally needed. | ||
3643 | </note> | ||
3644 | </para></listitem> | ||
3645 | <listitem><para> | ||
3646 | <emphasis>Quote All Assignments ("<replaceable>value</replaceable>"):</emphasis> | ||
3647 | Use double quotes around values in all variable | ||
3648 | assignments (e.g. | ||
3649 | <filename>"<replaceable>value</replaceable>"</filename>). | ||
3650 | Following is an example: | ||
3651 | <literallayout class='monospaced'> | ||
3652 | VAR1 = "${OTHERVAR}" | ||
3653 | VAR2 = "The version is ${PV}" | ||
3654 | </literallayout> | ||
3655 | </para></listitem> | ||
3656 | <listitem><para> | ||
3657 | <emphasis>Conditional Assignment (?=):</emphasis> | ||
3658 | Conditional assignment is used to assign a | ||
3659 | value to a variable, but only when the variable is | ||
3660 | currently unset. | ||
3661 | Use the question mark followed by the equal sign | ||
3662 | (<filename>?=</filename>) to make a "soft" assignment | ||
3663 | used for conditional assignment. | ||
3664 | Typically, "soft" assignments are used in the | ||
3665 | <filename>local.conf</filename> file for variables | ||
3666 | that are allowed to come through from the external | ||
3667 | environment. | ||
3668 | </para> | ||
3669 | |||
3670 | <para>Here is an example where | ||
3671 | <filename>VAR1</filename> is set to "New value" if | ||
3672 | it is currently empty. | ||
3673 | However, if <filename>VAR1</filename> has already been | ||
3674 | set, it remains unchanged: | ||
3675 | <literallayout class='monospaced'> | ||
3676 | VAR1 ?= "New value" | ||
3677 | </literallayout> | ||
3678 | In this next example, <filename>VAR1</filename> | ||
3679 | is left with the value "Original value": | ||
3680 | <literallayout class='monospaced'> | ||
3681 | VAR1 = "Original value" | ||
3682 | VAR1 ?= "New value" | ||
3683 | </literallayout> | ||
3684 | </para></listitem> | ||
3685 | <listitem><para> | ||
3686 | <emphasis>Appending (+=):</emphasis> | ||
3687 | Use the plus character followed by the equals sign | ||
3688 | (<filename>+=</filename>) to append values to existing | ||
3689 | variables. | ||
3690 | <note> | ||
3691 | This operator adds a space between the existing | ||
3692 | content of the variable and the new content. | ||
3693 | </note></para> | ||
3694 | |||
3695 | <para>Here is an example: | ||
3696 | <literallayout class='monospaced'> | ||
3697 | SRC_URI += "file://fix-makefile.patch" | ||
3698 | </literallayout> | ||
3699 | </para></listitem> | ||
3700 | <listitem><para> | ||
3701 | <emphasis>Prepending (=+):</emphasis> | ||
3702 | Use the equals sign followed by the plus character | ||
3703 | (<filename>=+</filename>) to prepend values to existing | ||
3704 | variables. | ||
3705 | <note> | ||
3706 | This operator adds a space between the new content | ||
3707 | and the existing content of the variable. | ||
3708 | </note></para> | ||
3709 | |||
3710 | <para>Here is an example: | ||
3711 | <literallayout class='monospaced'> | ||
3712 | VAR =+ "Starts" | ||
3713 | </literallayout> | ||
3714 | </para></listitem> | ||
3715 | <listitem><para> | ||
3716 | <emphasis>Appending (_append):</emphasis> | ||
3717 | Use the <filename>_append</filename> operator to | ||
3718 | append values to existing variables. | ||
3719 | This operator does not add any additional space. | ||
3720 | Also, the operator is applied after all the | ||
3721 | <filename>+=</filename>, and | ||
3722 | <filename>=+</filename> operators have been applied and | ||
3723 | after all <filename>=</filename> assignments have | ||
3724 | occurred. | ||
3725 | </para> | ||
3726 | |||
3727 | <para>The following example shows the space being | ||
3728 | explicitly added to the start to ensure the appended | ||
3729 | value is not merged with the existing value: | ||
3730 | <literallayout class='monospaced'> | ||
3731 | SRC_URI_append = " file://fix-makefile.patch" | ||
3732 | </literallayout> | ||
3733 | You can also use the <filename>_append</filename> | ||
3734 | operator with overrides, which results in the actions | ||
3735 | only being performed for the specified target or | ||
3736 | machine: | ||
3737 | <literallayout class='monospaced'> | ||
3738 | SRC_URI_append_sh4 = " file://fix-makefile.patch" | ||
3739 | </literallayout> | ||
3740 | </para></listitem> | ||
3741 | <listitem><para> | ||
3742 | <emphasis>Prepending (_prepend):</emphasis> | ||
3743 | Use the <filename>_prepend</filename> operator to | ||
3744 | prepend values to existing variables. | ||
3745 | This operator does not add any additional space. | ||
3746 | Also, the operator is applied after all the | ||
3747 | <filename>+=</filename>, and | ||
3748 | <filename>=+</filename> operators have been applied and | ||
3749 | after all <filename>=</filename> assignments have | ||
3750 | occurred. | ||
3751 | </para> | ||
3752 | |||
3753 | <para>The following example shows the space being | ||
3754 | explicitly added to the end to ensure the prepended | ||
3755 | value is not merged with the existing value: | ||
3756 | <literallayout class='monospaced'> | ||
3757 | CFLAGS_prepend = "-I${S}/myincludes " | ||
3758 | </literallayout> | ||
3759 | You can also use the <filename>_prepend</filename> | ||
3760 | operator with overrides, which results in the actions | ||
3761 | only being performed for the specified target or | ||
3762 | machine: | ||
3763 | <literallayout class='monospaced'> | ||
3764 | CFLAGS_prepend_sh4 = "-I${S}/myincludes " | ||
3765 | </literallayout> | ||
3766 | </para></listitem> | ||
3767 | <listitem><para> | ||
3768 | <emphasis>Overrides:</emphasis> | ||
3769 | You can use overrides to set a value conditionally, | ||
3770 | typically based on how the recipe is being built. | ||
3771 | For example, to set the | ||
3772 | <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> | ||
3773 | variable's value to "standard/base" for any target | ||
3774 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>, | ||
3775 | except for qemuarm where it should be set to | ||
3776 | "standard/arm-versatile-926ejs", you would do the | ||
3777 | following: | ||
3778 | <literallayout class='monospaced'> | ||
3779 | KBRANCH = "standard/base" | ||
3780 | KBRANCH_qemuarm = "standard/arm-versatile-926ejs" | ||
3781 | </literallayout> | ||
3782 | Overrides are also used to separate alternate values | ||
3783 | of a variable in other situations. | ||
3784 | For example, when setting variables such as | ||
3785 | <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink> | ||
3786 | and | ||
3787 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> | ||
3788 | that are specific to individual packages produced by | ||
3789 | a recipe, you should always use an override that | ||
3790 | specifies the name of the package. | ||
3791 | </para></listitem> | ||
3792 | <listitem><para> | ||
3793 | <emphasis>Indentation:</emphasis> | ||
3794 | Use spaces for indentation rather than than tabs. | ||
3795 | For shell functions, both currently work. | ||
3796 | However, it is a policy decision of the Yocto Project | ||
3797 | to use tabs in shell functions. | ||
3798 | Realize that some layers have a policy to use spaces | ||
3799 | for all indentation. | ||
3800 | </para></listitem> | ||
3801 | <listitem><para> | ||
3802 | <emphasis>Using Python for Complex Operations:</emphasis> | ||
3803 | For more advanced processing, it is possible to use | ||
3804 | Python code during variable assignments (e.g. | ||
3805 | search and replacement on a variable).</para> | ||
3806 | |||
3807 | <para>You indicate Python code using the | ||
3808 | <filename>${@<replaceable>python_code</replaceable>}</filename> | ||
3809 | syntax for the variable assignment: | ||
3810 | <literallayout class='monospaced'> | ||
3811 | SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz | ||
3812 | </literallayout> | ||
3813 | </para></listitem> | ||
3814 | <listitem><para> | ||
3815 | <emphasis>Shell Function Syntax:</emphasis> | ||
3816 | Write shell functions as if you were writing a shell | ||
3817 | script when you describe a list of actions to take. | ||
3818 | You should ensure that your script works with a generic | ||
3819 | <filename>sh</filename> and that it does not require | ||
3820 | any <filename>bash</filename> or other shell-specific | ||
3821 | functionality. | ||
3822 | The same considerations apply to various system | ||
3823 | utilities (e.g. <filename>sed</filename>, | ||
3824 | <filename>grep</filename>, <filename>awk</filename>, | ||
3825 | and so forth) that you might wish to use. | ||
3826 | If in doubt, you should check with multiple | ||
3827 | implementations - including those from BusyBox. | ||
3828 | </para></listitem> | ||
3829 | </itemizedlist> | ||
3830 | </para> | ||
3831 | </section> | ||
3508 | </section> | 3832 | </section> |
3509 | 3833 | ||
3510 | <section id="platdev-newmachine"> | 3834 | <section id="platdev-newmachine"> |