summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml113
-rw-r--r--documentation/ref-manual/ref-structure.xml28
2 files changed, 137 insertions, 4 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 3af40c2392..4a58a6f490 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -888,6 +888,119 @@
888 </section> 888 </section>
889 </section> 889 </section>
890 890
891 <section id='creating-a-custom-template-configuration-directory'>
892 <title>Creating a Custom Template Configuration Directory</title>
893
894 <para>
895 You might find yourself repeating the same configurations for
896 a particular build or group of builds.
897 If so, rather than repeatedly editing your
898 <filename>local.conf</filename> and possibly your
899 <filename>bblayers.conf</filename>, you can set up a
900 custom directory that has your configurations, and then
901 point the OpenEmbedded build system to that directory to find
902 the configurations.
903 </para>
904
905 <para>
906 The OpenEmbedded build system uses the environment variable
907 <filename>TEMPLATECONF</filename> to point to the directory
908 from which it gathers configuration information that ultimately
909 ends up in the
910 <link linkend='build-directory'>Build Directory's</link>
911 <filename>conf</filename> directory.
912 By default, <filename>TEMPLATECONF</filename> points here:
913 <literallayout class='monospaced'>
914 TEMPLATECONF=${TEMPLATECONF:-meta-yocto/conf}
915 </literallayout>
916 This is the directory that the build system finds templates
917 with which to build some key configuration files.
918 If you look at this directory, you will see the
919 <filename>bblayers.conf.sample</filename>,
920 <filename>local.conf.sample</filename>, and
921 <filename>site.conf.sample</filename> configuration files.
922 The build system uses these files to form the respective
923 <filename>bblayers.conf</filename>,
924 <filename>local.conf</filename>, and the
925 <filename>site.conf</filename> configuration files it places in
926 the <filename>conf</filename> directory with the
927 Build Directory.
928 </para>
929
930 <para>
931 To override these default configuration files with
932 configurations you want used with every build, simply point the
933 <filename>TEMPLATECONF</filename> to your directory.
934 The <filename>TEMPLATECONF</filename> variable is set in the
935 <filename>.templateconf</filename> file, which is in the
936 top-level
937 <link linkend='source-directory'>Source Directory</link>
938 folder (e.g. <filename>poky</filename>).
939 Edit the <filename>.templateconf</filename> so that it points
940 to your directory.
941 Best practices dictate that you should keep your
942 template configuration directory in your custom distribution layer.
943 For example, suppose you have a layer named
944 <filename>meta-mylayer</filename> located in your home directory
945 and you want your template configuration directory named
946 <filename>myconf</filename>.
947 Changing the <filename>.templateconf</filename> as follows
948 causes the OpenEmbedded build system to look in your directory
949 and base its configuration files on the
950 <filename>*.sample</filename> configuration files it finds.
951 The final configuration files (i.e.
952 <filename>local.conf</filename> and
953 <filename>bblayers.conf</filename> ultimately still end up in
954 your Build Directory, but they are based on your
955 <filename>*.sample</filename> files.
956 <literallayout class='monospaced'>
957 TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf}
958 </literallayout>
959 </para>
960
961 <para>
962 Aside from the <filename>*.sample</filename> configuration files,
963 the <filename>conf-notes.txt</filename> also resides in the
964 default <filename>meta-yocto/conf</filename> directory.
965 The scripts that set up the build environment
966 (i.e.
967 <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
968 and
969 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>)
970 use this file to display BitBake targets as part of the script
971 output.
972 Customizing this <filename>conf-notes.txt</filename> file is a
973 good way to make sure your list of custom targets appears
974 as part of the script's output.
975 </para>
976
977 <para>
978 Here is output from either of the setup scripts by default:
979 <literallayout class='monospaced'>
980 $ source oe-init-build-env-memres
981 No port specified, using dynamically selected port
982
983 ### Shell environment set up for builds. ###
984
985 You can now run 'bitbake &lt;target&gt;'
986
987 Common targets are:
988 core-image-minimal
989 core-image-sato
990 meta-toolchain
991 adt-installer
992 meta-ide-support
993 </literallayout>
994 </para>
995
996 <para>
997 Changing the listed common targets is as easy as editing your
998 version of <filename>conf-notes.txt</filename> in your
999 custom template configuration directory and making sure you
1000 have <filename>TEMPLATECONF</filename> pointing to it.
1001 </para>
1002 </section>
1003
891 <section id='usingpoky-extend-customimage'> 1004 <section id='usingpoky-extend-customimage'>
892 <title>Customizing Images</title> 1005 <title>Customizing Images</title>
893 1006
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
index 1549d90357..c849dbda33 100644
--- a/documentation/ref-manual/ref-structure.xml
+++ b/documentation/ref-manual/ref-structure.xml
@@ -240,8 +240,10 @@
240 Should you have custom distributions, it is very easy to modify 240 Should you have custom distributions, it is very easy to modify
241 this configuration file to include your targets for your 241 this configuration file to include your targets for your
242 distribution. 242 distribution.
243 Simply edit the list within the file and when you run the 243 See the
244 environment setup script you see your customized list of targets. 244 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
245 section in the Yocto Project Development Manual for more
246 information.
245 </para> 247 </para>
246 248
247 <para> 249 <para>
@@ -258,6 +260,14 @@
258 <literallayout class='monospaced'> 260 <literallayout class='monospaced'>
259 $ source &OE_INIT_FILE; ~/mybuilds 261 $ source &OE_INIT_FILE; ~/mybuilds
260 </literallayout> 262 </literallayout>
263 The OpenEmbedded build system uses the template configuration
264 files, which are found by default in the
265 <filename>meta-yocto/conf</filename> directory in the
266 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
267 See the
268 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
269 section in the Yocto Project Development Manual for more
270 information.
261 <note> 271 <note>
262 The OpenEmbedded build system does not support file or directory names that 272 The OpenEmbedded build system does not support file or directory names that
263 contain spaces. 273 contain spaces.
@@ -349,8 +359,10 @@
349 Should you have custom distributions, it is very easy to modify 359 Should you have custom distributions, it is very easy to modify
350 this configuration file to include your targets for your 360 this configuration file to include your targets for your
351 distribution. 361 distribution.
352 Simply edit the list within the file and when you run the 362 See the
353 environment setup script you see your customized list of targets. 363 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
364 section in the Yocto Project Development Manual for more
365 information.
354 </para> 366 </para>
355 367
356 <para> 368 <para>
@@ -368,6 +380,14 @@
368 <literallayout class='monospaced'> 380 <literallayout class='monospaced'>
369 $ source oe-init-build-env-memres ~/mybuilds 381 $ source oe-init-build-env-memres ~/mybuilds
370 </literallayout> 382 </literallayout>
383 The OpenEmbedded build system uses the template configuration
384 files, which are found by default in the
385 <filename>meta-yocto/conf</filename> directory in the
386 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
387 See the
388 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
389 section in the Yocto Project Development Manual for more
390 information.
371 <note> 391 <note>
372 The OpenEmbedded build system does not support file or 392 The OpenEmbedded build system does not support file or
373 directory names that contain spaces. 393 directory names that contain spaces.