summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-03-21 07:30:14 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-03-25 09:41:13 +0100
commitb3732ab1aa9d03ae0bc8afa21c25dedc8653831c (patch)
tree098ec5688412603d2ebe47f6b39d0f14bacc1326 /documentation/dev-manual
parentfcbe72179c01fdb93a58a2016eef5e89ab0c63ba (diff)
downloadpoky-b3732ab1aa9d03ae0bc8afa21c25dedc8653831c.tar.gz
dev-manual: Cleaned up layer naming terminology
Reality dictates that the YP does not treat layer naming consistently. Layers are talked about as the "meta-whatever" layer and never the "whatever" layer. However, the tooling sometimes appends or uses just the "whatever" part of the layer name. A good example is the meta-yocto-bsp configuration file. All the variables in there use just the root name of a layer's name. In the manuals, I had been distinguishing the layer name as just the "whatever" part sans "meta-". I talked about the convention of using "meta-" in front of layer names, etc. Well, this is confusing in light of how everyone says a layer's name is "meta-whatever". So, I fixed all this up. (From yocto-docs rev: 79e52f6ccf4246fc69a460ce9d3a4a18720a9442) 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.xml171
1 files changed, 111 insertions, 60 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 11b53ac116..11a7065c4e 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -73,14 +73,18 @@
73 meta-GUI_xyz 73 meta-GUI_xyz
74 meta-mymachine 74 meta-mymachine
75 </literallayout> 75 </literallayout>
76 Realize that the name of your layer does not include 76 With rare exceptions, a layer's name follows this
77 the "meta-" string. 77 form:
78 For example, the names of the previous three layers 78 <literallayout class='monospaced'>
79 are "mylayer", "GUI_xyz", and "mymachine". 79 meta-<replaceable>root_name</replaceable>
80 Following this layer directory naming convention can 80 </literallayout>
81 save you trouble later when tools or components 81 Following this layer naming convention can
82 "assume" your layer resides in a directory whose name 82 save you trouble later when tools, components, or
83 starts with "meta-". 83 variables "assume" your layer name begins with "meta-".
84 A notable example is in configuration files as
85 shown in the following step where layer names without
86 the "meta-" string are appended
87 to several variables used in the configuration.
84 </para></listitem> 88 </para></listitem>
85 <listitem><para> 89 <listitem><para>
86 <emphasis>Create a Layer Configuration 90 <emphasis>Create a Layer Configuration
@@ -141,7 +145,7 @@
141 <listitem><para> 145 <listitem><para>
142 The 146 The
143 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename> 147 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
144 variable is appended with the layer name, 148 variable is appended with the layer's root name,
145 which is "yoctobsp" in this example. 149 which is "yoctobsp" in this example.
146 </para></listitem> 150 </para></listitem>
147 <listitem><para> 151 <listitem><para>
@@ -637,7 +641,8 @@
637 641
638 <para> 642 <para>
639 BitBake parses each <filename>conf/layer.conf</filename> file 643 BitBake parses each <filename>conf/layer.conf</filename> file
640 as specified in the <filename>BBLAYERS</filename> variable 644 from the top down as specified in the
645 <filename>BBLAYERS</filename> variable
641 within the <filename>conf/bblayers.conf</filename> file. 646 within the <filename>conf/bblayers.conf</filename> file.
642 During the processing of each 647 During the processing of each
643 <filename>conf/layer.conf</filename> file, BitBake adds the 648 <filename>conf/layer.conf</filename> file, BitBake adds the
@@ -815,8 +820,7 @@
815 <para> 820 <para>
816 To specify the layer's priority manually, use the 821 To specify the layer's priority manually, use the
817 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink> 822 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
818 variable. 823 variable and append the layer's root name:
819 For example:
820 <literallayout class='monospaced'> 824 <literallayout class='monospaced'>
821 BBFILE_PRIORITY_mylayer = "1" 825 BBFILE_PRIORITY_mylayer = "1"
822 </literallayout> 826 </literallayout>
@@ -837,7 +841,8 @@
837 <title>Managing Layers</title> 841 <title>Managing Layers</title>
838 842
839 <para> 843 <para>
840 You can use the BitBake layer management tool to provide a view 844 You can use the BitBake layer management tool
845 <filename>bitbake-layers</filename> to provide a view
841 into the structure of recipes across a multi-layer project. 846 into the structure of recipes across a multi-layer project.
842 Being able to generate output that reports on configured layers 847 Being able to generate output that reports on configured layers
843 with their paths and priorities and on 848 with their paths and priorities and on
@@ -846,42 +851,88 @@
846 </para> 851 </para>
847 852
848 <para> 853 <para>
849 Use the following form when running the layer management tool. 854 For help on the BitBake layer management tool, use the
855 following command:
850 <literallayout class='monospaced'> 856 <literallayout class='monospaced'>
851 $ bitbake-layers <replaceable>command</replaceable> [<replaceable>arguments</replaceable>] 857 $ bitbake-layers --help
858 NOTE: Starting bitbake server...
859 usage: bitbake-layers [-d] [-q] [-F] [--color COLOR] [-h] &lt;subcommand&gt; ...
860
861 BitBake layers utility
862
863 optional arguments:
864 -d, --debug Enable debug output
865 -q, --quiet Print only errors
866 -F, --force Force add without recipe parse verification
867 --color COLOR Colorize output (where COLOR is auto, always, never)
868 -h, --help show this help message and exit
869
870 subcommands:
871 &lt;subcommand&gt;
872 show-layers show current configured layers.
873 show-overlayed list overlayed recipes (where the same recipe exists
874 in another layer)
875 show-recipes list available recipes, showing the layer they are
876 provided by
877 show-appends list bbappend files and recipe files they apply to
878 show-cross-depends Show dependencies between recipes that cross layer
879 boundaries.
880 add-layer Add one or more layers to bblayers.conf.
881 remove-layer Remove one or more layers from bblayers.conf.
882 flatten flatten layer configuration into a separate output
883 directory.
884 layerindex-fetch Fetches a layer from a layer index along with its
885 dependent layers, and adds them to conf/bblayers.conf.
886 layerindex-show-depends
887 Find layer dependencies from layer index.
888 create-layer Create a basic layer
889
890 Use bitbake-layers &lt;subcommand&gt; --help to get help on a specific command
852 </literallayout> 891 </literallayout>
892 </para>
893
894 <para>
853 The following list describes the available commands: 895 The following list describes the available commands:
854 <itemizedlist> 896 <itemizedlist>
855 <listitem><para><filename><emphasis>help:</emphasis></filename> 897 <listitem><para>
898 <emphasis><filename>help:</filename></emphasis>
856 Displays general help or help on a specified command. 899 Displays general help or help on a specified command.
857 </para></listitem> 900 </para></listitem>
858 <listitem><para><filename><emphasis>show-layers:</emphasis></filename> 901 <listitem><para>
902 <emphasis><filename>show-layers:</filename></emphasis>
859 Shows the current configured layers. 903 Shows the current configured layers.
860 </para></listitem> 904 </para></listitem>
861 <listitem><para><filename><emphasis>show-recipes:</emphasis></filename> 905 <listitem><para>
862 Lists available recipes and the layers that provide them. 906 <emphasis><filename>show-overlayed:</filename></emphasis>
863 </para></listitem>
864 <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename>
865 Lists overlayed recipes. 907 Lists overlayed recipes.
866 A recipe is overlayed when a recipe with the same name 908 A recipe is overlayed when a recipe with the same name
867 exists in another layer that has a higher layer 909 exists in another layer that has a higher layer
868 priority. 910 priority.
869 </para></listitem> 911 </para></listitem>
870 <listitem><para><filename><emphasis>show-appends:</emphasis></filename> 912 <listitem><para>
913 <emphasis><filename>show-recipes:</filename></emphasis>
914 Lists available recipes and the layers that provide them.
915 </para></listitem>
916 <listitem><para>
917 <emphasis><filename>show-appends:</filename></emphasis>
871 Lists <filename>.bbappend</filename> files and the 918 Lists <filename>.bbappend</filename> files and the
872 recipe files to which they apply. 919 recipe files to which they apply.
873 </para></listitem> 920 </para></listitem>
874 <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename> 921 <listitem><para>
922 <emphasis><filename>show-cross-depends:</filename></emphasis>
875 Lists dependency relationships between recipes that 923 Lists dependency relationships between recipes that
876 cross layer boundaries. 924 cross layer boundaries.
877 </para></listitem> 925 </para></listitem>
878 <listitem><para><filename><emphasis>add-layer:</emphasis></filename> 926 <listitem><para>
927 <emphasis><filename>add-layer:</filename></emphasis>
879 Adds a layer to <filename>bblayers.conf</filename>. 928 Adds a layer to <filename>bblayers.conf</filename>.
880 </para></listitem> 929 </para></listitem>
881 <listitem><para><filename><emphasis>remove-layer:</emphasis></filename> 930 <listitem><para>
931 <emphasis><filename>remove-layer:</filename></emphasis>
882 Removes a layer from <filename>bblayers.conf</filename> 932 Removes a layer from <filename>bblayers.conf</filename>
883 </para></listitem> 933 </para></listitem>
884 <listitem><para><filename><emphasis>flatten:</emphasis></filename> 934 <listitem><para>
935 <emphasis><filename>flatten:</filename></emphasis>
885 Flattens the layer configuration into a separate output 936 Flattens the layer configuration into a separate output
886 directory. 937 directory.
887 Flattening your layer configuration builds a "flattened" 938 Flattening your layer configuration builds a "flattened"
@@ -892,18 +943,21 @@
892 You might have to perform some manual cleanup of the 943 You might have to perform some manual cleanup of the
893 flattened layer as follows: 944 flattened layer as follows:
894 <itemizedlist> 945 <itemizedlist>
895 <listitem><para>Non-recipe files (such as patches) 946 <listitem><para>
947 Non-recipe files (such as patches)
896 are overwritten. 948 are overwritten.
897 The flatten command shows a warning for these 949 The flatten command shows a warning for these
898 files. 950 files.
899 </para></listitem> 951 </para></listitem>
900 <listitem><para>Anything beyond the normal layer 952 <listitem><para>
953 Anything beyond the normal layer
901 setup has been added to the 954 setup has been added to the
902 <filename>layer.conf</filename> file. 955 <filename>layer.conf</filename> file.
903 Only the lowest priority layer's 956 Only the lowest priority layer's
904 <filename>layer.conf</filename> is used. 957 <filename>layer.conf</filename> is used.
905 </para></listitem> 958 </para></listitem>
906 <listitem><para>Overridden and appended items from 959 <listitem><para>
960 Overridden and appended items from
907 <filename>.bbappend</filename> files need to be 961 <filename>.bbappend</filename> files need to be
908 cleaned up. 962 cleaned up.
909 The contents of each 963 The contents of each
@@ -1568,47 +1622,43 @@
1568 and have sourced the build environment setup script 1622 and have sourced the build environment setup script
1569 (i.e. 1623 (i.e.
1570 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>). 1624 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>).
1571 Here is the basic <filename>recipetool</filename> syntax: 1625 To get help on the tool, use the following command:
1572 <note>
1573 Running <filename>recipetool -h</filename> or
1574 <filename>recipetool create -h</filename> produces the
1575 Python-generated help, which presented differently
1576 than what follows here.
1577 </note>
1578 <literallayout class='monospaced'> 1626 <literallayout class='monospaced'>
1579 recipetool -h 1627 $ recipetool -h
1580 recipetool create [-h] 1628 NOTE: Starting bitbake server...
1581 recipetool [-d] [-q] [--color auto | always | never ] create -o <replaceable>OUTFILE</replaceable> [-m] [-x <replaceable>EXTERNALSRC</replaceable>] <replaceable>source</replaceable> 1629 usage: recipetool [-d] [-q] [--color COLOR] [-h] &lt;subcommand&gt; ...
1582 1630
1583 -d Enables debug output. 1631 OpenEmbedded recipe tool
1584 -q Outputs only errors (quiet mode). 1632
1585 --color Colorizes the output automatically, always, or never. 1633 options:
1586 -h Displays Python generated syntax for recipetool. 1634 -d, --debug Enable debug output
1587 create Causes recipetool to create a base recipe. The create 1635 -q, --quiet Print only errors
1588 command is further defined with these options: 1636 --color COLOR Colorize output (where COLOR is auto, always, never)
1589 1637 -h, --help show this help message and exit
1590 -o <replaceable>OUTFILE</replaceable> Specifies the full path and filename for the generated 1638
1591 recipe. 1639 subcommands:
1592 -m Causes the recipe to be machine-specific rather than 1640 create Create a new recipe
1593 architecture-specific (default). 1641 newappend Create a bbappend for the specified target in the specified
1594 -x <replaceable>EXTERNALSRC</replaceable> Fetches and extracts source files from <replaceable>source</replaceable> 1642 layer
1595 and places them in <replaceable>EXTERNALSRC</replaceable>. 1643 setvar Set a variable within a recipe
1596 <replaceable>source</replaceable> must be a URL. 1644 appendfile Create/update a bbappend to replace a target file
1597 -h Displays Python-generated syntax for create. 1645 appendsrcfiles Create/update a bbappend to add or replace source files
1598 <replaceable>source</replaceable> Specifies the source code on which to base the 1646 appendsrcfile Create/update a bbappend to add or replace a source file
1599 recipe. 1647 Use recipetool &lt;subcommand&gt; --help to get help on a specific command
1600 </literallayout> 1648 </literallayout>
1601 </para> 1649 </para>
1602 1650
1603 <para> 1651 <para>
1604 Running <filename>recipetool create -o</filename>&nbsp;<replaceable>OUTFILE</replaceable> 1652 Running
1653 <filename>recipetool create -o</filename>&nbsp;<replaceable>OUTFILE</replaceable>
1605 creates the base recipe and locates it properly in the 1654 creates the base recipe and locates it properly in the
1606 layer that contains your source files. 1655 layer that contains your source files.
1607 Following are some syntax examples: 1656 Following are some syntax examples:
1608 </para> 1657 </para>
1609 1658
1610 <para> 1659 <para>
1611 Use this syntax to generate a recipe based on <replaceable>source</replaceable>. 1660 Use this syntax to generate a recipe based on
1661 <replaceable>source</replaceable>.
1612 Once generated, the recipe resides in the existing source 1662 Once generated, the recipe resides in the existing source
1613 code layer: 1663 code layer:
1614 <literallayout class='monospaced'> 1664 <literallayout class='monospaced'>
@@ -1621,7 +1671,8 @@
1621 <literallayout class='monospaced'> 1671 <literallayout class='monospaced'>
1622 recipetool create -o <replaceable>OUTFILE</replaceable> -x <replaceable>EXTERNALSRC</replaceable> <replaceable>source</replaceable> 1672 recipetool create -o <replaceable>OUTFILE</replaceable> -x <replaceable>EXTERNALSRC</replaceable> <replaceable>source</replaceable>
1623 </literallayout> 1673 </literallayout>
1624 Use this syntax to generate a recipe based on <replaceable>source</replaceable>. 1674 Use this syntax to generate a recipe based on
1675 <replaceable>source</replaceable>.
1625 The options direct <filename>recipetool</filename> to 1676 The options direct <filename>recipetool</filename> to
1626 generate debugging information. 1677 generate debugging information.
1627 Once generated, the recipe resides in the existing source 1678 Once generated, the recipe resides in the existing source