summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml193
1 files changed, 106 insertions, 87 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index ac82dad0a3..2d6bdf5cd9 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -108,7 +108,7 @@
108 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" 108 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
109 section in the Yocto Project Board Support Package (BSP) 109 section in the Yocto Project Board Support Package (BSP)
110 Developer's Guide and the 110 Developer's Guide and the
111 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>" 111 "<link linkend='creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</link>"
112 section further down in this manual. 112 section further down in this manual.
113 </para> 113 </para>
114 114
@@ -968,122 +968,141 @@
968 </para> 968 </para>
969 </section> 969 </section>
970 970
971 <section id='creating-a-general-layer-using-the-yocto-layer-script'> 971 <section id='creating-a-general-layer-using-the-bitbake-layers-script'>
972 <title>Creating a General Layer Using the yocto-layer Script</title> 972 <title>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</title>
973 973
974 <para> 974 <para>
975 The <filename>yocto-layer</filename> script simplifies 975 The <filename>bitbake-layers</filename> script with the
976 <filename>create-layer</filename> subcommand simplifies
976 creating a new general layer. 977 creating a new general layer.
977 <note> 978 <note><title>Notes</title>
978 For information on BSP layers, see the 979 <itemizedlist>
979 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" 980 <listitem><para>
980 section in the Yocto Project Board Specific (BSP) 981 For information on BSP layers, see the
981 Developer's Guide. 982 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
983 section in the Yocto Project Board Specific (BSP)
984 Developer's Guide.
985 </para></listitem>
986 <listitem><para>
987 The <filename>bitbake-layers</filename> script
988 replaces the <filename>yocto-layer</filename>
989 script, which is deprecated in the Yocto Project
990 2.4 release.
991 The <filename>yocto-layer</filename> script
992 continues to function as part of the 2.4 release
993 but will be removed post 2.4.
994 </para></listitem>
995 </itemizedlist>
982 </note> 996 </note>
983 The default mode of the script's operation is to prompt you for 997 The default mode of the script's operation with this
984 information needed to generate the layer: 998 subcommand is to create a layer with the following:
985 <itemizedlist> 999 <itemizedlist>
986 <listitem><para>The layer priority. 1000 <listitem><para>A layer priority of 6.
987 </para></listitem> 1001 </para></listitem>
988 <listitem><para>Whether or not to create a sample recipe. 1002 <listitem><para>A <filename>conf</filename>
1003 subdirectory that contains a
1004 <filename>layer.conf</filename> file.
989 </para></listitem> 1005 </para></listitem>
990 <listitem><para>Whether or not to create a sample 1006 <listitem><para>
991 append file. 1007 A <filename>recipes-example</filename> subdirectory
992 </para></listitem> 1008 that contains a further subdirectory named
993 </itemizedlist> 1009 <filename>example</filename>, which contains
994 </para> 1010 an <filename>example.bb</filename> recipe file.
995
996 <para>
997 Use the <filename>yocto-layer create</filename> sub-command
998 to create a new general layer.
999 In its simplest form, you can create a layer as follows:
1000 <literallayout class='monospaced'>
1001 $ yocto-layer create mylayer
1002 </literallayout>
1003 The previous example creates a layer named
1004 <filename>meta-mylayer</filename> in the current directory.
1005 </para>
1006
1007 <para>
1008 As the <filename>yocto-layer create</filename> command runs,
1009 default values for the prompts appear in brackets.
1010 Pressing enter without supplying anything for the prompts
1011 or pressing enter and providing an invalid response causes the
1012 script to accept the default value.
1013 Once the script completes, the new layer
1014 is created in the current working directory.
1015 The script names the layer by prepending
1016 <filename>meta-</filename> to the name you provide.
1017 </para>
1018
1019 <para>
1020 Minimally, the script creates the following within the layer:
1021 <itemizedlist>
1022 <listitem><para><emphasis>The <filename>conf</filename>
1023 directory:</emphasis>
1024 This directory contains the layer's configuration file.
1025 The root name for the file is the same as the root name
1026 your provided for the layer (e.g.
1027 <filename><replaceable>layer</replaceable>.conf</filename>).
1028 </para></listitem> 1011 </para></listitem>
1029 <listitem><para><emphasis>The 1012 <listitem><para>A <filename >COPYING.MIT</filename>,
1030 <filename>COPYING.MIT</filename> file:</emphasis> 1013 which is the license statement for the layer.
1031 The copyright and use notice for the software. 1014 The script assumes you want to use the MIT license,
1015 which is typical for most layers, for the contents of
1016 the layer itself.
1032 </para></listitem> 1017 </para></listitem>
1033 <listitem><para><emphasis>The <filename>README</filename> 1018 <listitem><para>
1034 file:</emphasis> 1019 A <filename>README</filename> file, which is a file
1035 A file describing the contents of your new layer. 1020 describing the contents of your new layer.
1036 </para></listitem> 1021 </para></listitem>
1037 </itemizedlist> 1022 </itemizedlist>
1038 </para> 1023 </para>
1039 1024
1040 <para> 1025 <para>
1041 If you choose to generate a sample recipe file, the script 1026 In its simplest form, you can use the following command form
1042 prompts you for the name for the recipe and then creates it 1027 to create a layer.
1043 in <filename><replaceable>layer</replaceable>/recipes-example/example/</filename>. 1028 The command creates a layer whose name corresponds to
1044 The script creates a <filename>.bb</filename> file and a 1029 <replaceable>your_layer_name</replaceable> in the current
1045 directory, which contains a sample 1030 directory:
1046 <filename>helloworld.c</filename> source file, along with 1031 <literallayout class='monospaced'>
1047 a sample patch file. 1032 $ bitbake-layers create-layer <replaceable>your_layer_name</replaceable>
1048 If you do not provide a recipe name, the script uses 1033 </literallayout>
1049 "example".
1050 </para> 1034 </para>
1051 1035
1052 <para> 1036 <para>
1053 If you choose to generate a sample append file, the script 1037 If you want to set the priority of the layer to other than the
1054 prompts you for the name for the file and then creates it 1038 default value of "6", you can either use the
1055 in <filename><replaceable>layer</replaceable>/recipes-example-bbappend/example-bbappend/</filename>. 1039 <filename>&dash;&dash;priority</filename> option or you can
1056 The script creates a <filename>.bbappend</filename> file and a 1040 edit the
1057 directory, which contains a sample patch file. 1041 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
1058 If you do not provide a recipe name, the script uses 1042 value in the <filename>conf/layer.conf</filename> after the
1059 "example". 1043 script creates it.
1060 The script also prompts you for the version of the append file. 1044 Furthermore, if you want to give the example recipe file
1061 The version should match the recipe to which the append file 1045 some name other than the default, you can
1062 is associated. 1046 use the
1047 <filename>&dash;&dash;example-recipe-name</filename> option.
1063 </para> 1048 </para>
1064 1049
1065 <para> 1050 <para>
1066 The easiest way to see how the <filename>yocto-layer</filename> 1051 The easiest way to see how the
1067 script works is to experiment with the script. 1052 <filename>bitbake-layers create-layer</filename> command
1053 works is to experiment with the script.
1068 You can also read the usage information by entering the 1054 You can also read the usage information by entering the
1069 following: 1055 following:
1070 <literallayout class='monospaced'> 1056 <literallayout class='monospaced'>
1071 $ yocto-layer help 1057 $ bitbake-layers create-layer --help
1058 NOTE: Starting bitbake server...
1059 usage: bitbake-layers create-layer [-h] [--priority PRIORITY]
1060 [--example-recipe-name EXAMPLERECIPE]
1061 layerdir
1062
1063 Create a basic layer
1064
1065 positional arguments:
1066 layerdir Layer directory to create
1067
1068 optional arguments:
1069 -h, --help show this help message and exit
1070 --priority PRIORITY, -p PRIORITY
1071 Layer directory to create
1072 --example-recipe-name EXAMPLERECIPE, -e EXAMPLERECIPE
1073 Filename of the example recipe
1072 </literallayout> 1074 </literallayout>
1073 </para> 1075 </para>
1074 1076
1075 <para> 1077 <para>
1076 Once you create your general layer, you must add it to your 1078 Once you create your general layer, you must add it to your
1077 <filename>bblayers.conf</filename> file. 1079 <filename>bblayers.conf</filename> file.
1080 You can add your layer by using the
1081 <filename>bitbake-layers add-layer</filename> command:
1082 <literallayout class='monospaced'>
1083 $ bitbake-layers add-layer <replaceable>your_layer_name</replaceable>
1084 </literallayout>
1078 Here is an example where a layer named 1085 Here is an example where a layer named
1079 <filename>meta-mylayer</filename> is added: 1086 <filename>meta-scottrif</filename> is added and then the
1087 layers are shown using the
1088 <filename>bitbake-layers show-layers</filename> command:
1080 <literallayout class='monospaced'> 1089 <literallayout class='monospaced'>
1081 BBLAYERS = ?" \ 1090 $ bitbake-layers add-layer meta-scottrif
1082 /usr/local/src/yocto/meta \ 1091 NOTE: Starting bitbake server...
1083 /usr/local/src/yocto/meta-poky \ 1092 Loading cache: 100% |############################################| Time: 0:00:00
1084 /usr/local/src/yocto/meta-yocto-bsp \ 1093 Loaded 1275 entries from dependency cache.
1085 /usr/local/src/yocto/meta-mylayer \ 1094 Parsing recipes: 100% |##########################################| Time: 0:00:00
1086 " 1095 Parsing of 819 .bb files complete (817 cached, 2 parsed). 1276 targets, 44 skipped, 0 masked, 0 errors.
1096 $ bitbake-layers show-layers
1097 NOTE: Starting bitbake server...
1098 layer path priority
1099 ==========================================================================
1100 meta /home/scottrif/poky/meta 5
1101 meta-poky /home/scottrif/poky/meta-poky 5
1102 meta-yocto-bsp /home/scottrif/poky/meta-yocto-bsp 5
1103 meta-mylayer /home/scottrif/meta-mylayer 6
1104 workspace /home/scottrif/poky/build/workspace 99
1105 meta-scottrif /home/scottrif/poky/build/meta-scottrif 6
1087 </literallayout> 1106 </literallayout>
1088 Adding the layer to this file enables the build system to 1107 Adding the layer to this file enables the build system to
1089 locate the layer during the build. 1108 locate the layer during the build.
@@ -6060,7 +6079,7 @@ Some notes from Cal:
6060 configuration file makes it easier to reproduce the same 6079 configuration file makes it easier to reproduce the same
6061 build configuration when using multiple build machines. 6080 build configuration when using multiple build machines.
6062 See the 6081 See the
6063 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>" 6082 "<link linkend='creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</link>"
6064 section for information on how to quickly set up a layer. 6083 section for information on how to quickly set up a layer.
6065 </para></listitem> 6084 </para></listitem>
6066 <listitem><para><emphasis>Create the distribution configuration file:</emphasis> 6085 <listitem><para><emphasis>Create the distribution configuration file:</emphasis>