diff options
| -rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 113 | ||||
| -rw-r--r-- | documentation/ref-manual/ref-structure.xml | 28 |
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 3af40c2..4a58a6f 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -888,6 +888,119 @@ </section> </section> + <section id='creating-a-custom-template-configuration-directory'> + <title>Creating a Custom Template Configuration Directory</title> + + <para> + You might find yourself repeating the same configurations for + a particular build or group of builds. + If so, rather than repeatedly editing your + <filename>local.conf</filename> and possibly your + <filename>bblayers.conf</filename>, you can set up a + custom directory that has your configurations, and then + point the OpenEmbedded build system to that directory to find + the configurations. + </para> + + <para> + The OpenEmbedded build system uses the environment variable + <filename>TEMPLATECONF</filename> to point to the directory + from which it gathers configuration information that ultimately + ends up in the + <link linkend='build-directory'>Build Directory's</link> + <filename>conf</filename> directory. + By default, <filename>TEMPLATECONF</filename> points here: + <literallayout class='monospaced'> + TEMPLATECONF=${TEMPLATECONF:-meta-yocto/conf} + </literallayout> + This is the directory that the build system finds templates + with which to build some key configuration files. + If you look at this directory, you will see the + <filename>bblayers.conf.sample</filename>, + <filename>local.conf.sample</filename>, and + <filename>site.conf.sample</filename> configuration files. + The build system uses these files to form the respective + <filename>bblayers.conf</filename>, + <filename>local.conf</filename>, and the + <filename>site.conf</filename> configuration files it places in + the <filename>conf</filename> directory with the + Build Directory. + </para> + + <para> + To override these default configuration files with + configurations you want used with every build, simply point the + <filename>TEMPLATECONF</filename> to your directory. + The <filename>TEMPLATECONF</filename> variable is set in the + <filename>.templateconf</filename> file, which is in the + top-level + <link linkend='source-directory'>Source Directory</link> + folder (e.g. <filename>poky</filename>). + Edit the <filename>.templateconf</filename> so that it points + to your directory. + Best practices dictate that you should keep your + template configuration directory in your custom distribution layer. + For example, suppose you have a layer named + <filename>meta-mylayer</filename> located in your home directory + and you want your template configuration directory named + <filename>myconf</filename>. + Changing the <filename>.templateconf</filename> as follows + causes the OpenEmbedded build system to look in your directory + and base its configuration files on the + <filename>*.sample</filename> configuration files it finds. + The final configuration files (i.e. + <filename>local.conf</filename> and + <filename>bblayers.conf</filename> ultimately still end up in + your Build Directory, but they are based on your + <filename>*.sample</filename> files. + <literallayout class='monospaced'> + TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf} + </literallayout> + </para> + + <para> + Aside from the <filename>*.sample</filename> configuration files, + the <filename>conf-notes.txt</filename> also resides in the + default <filename>meta-yocto/conf</filename> directory. + The scripts that set up the build environment + (i.e. + <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink> + and + <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>) + use this file to display BitBake targets as part of the script + output. + Customizing this <filename>conf-notes.txt</filename> file is a + good way to make sure your list of custom targets appears + as part of the script's output. + </para> + + <para> + Here is output from either of the setup scripts by default: + <literallayout class='monospaced'> + $ source oe-init-build-env-memres + No port specified, using dynamically selected port + + ### Shell environment set up for builds. ### + + You can now run 'bitbake <target>' + + Common targets are: + core-image-minimal + core-image-sato + meta-toolchain + adt-installer + meta-ide-support + </literallayout> + </para> + + <para> + Changing the listed common targets is as easy as editing your + version of <filename>conf-notes.txt</filename> in your + custom template configuration directory and making sure you + have <filename>TEMPLATECONF</filename> pointing to it. + </para> + </section> + <section id='usingpoky-extend-customimage'> <title>Customizing Images</title> diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml index 1549d90..c849dbd 100644 --- a/documentation/ref-manual/ref-structure.xml +++ b/documentation/ref-manual/ref-structure.xml @@ -240,8 +240,10 @@ Should you have custom distributions, it is very easy to modify this configuration file to include your targets for your distribution. - Simply edit the list within the file and when you run the - environment setup script you see your customized list of targets. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" + section in the Yocto Project Development Manual for more + information. </para> <para> @@ -258,6 +260,14 @@ <literallayout class='monospaced'> $ source &OE_INIT_FILE; ~/mybuilds </literallayout> + The OpenEmbedded build system uses the template configuration + files, which are found by default in the + <filename>meta-yocto/conf</filename> directory in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" + section in the Yocto Project Development Manual for more + information. <note> The OpenEmbedded build system does not support file or directory names that contain spaces. @@ -349,8 +359,10 @@ Should you have custom distributions, it is very easy to modify this configuration file to include your targets for your distribution. - Simply edit the list within the file and when you run the - environment setup script you see your customized list of targets. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" + section in the Yocto Project Development Manual for more + information. </para> <para> @@ -368,6 +380,14 @@ <literallayout class='monospaced'> $ source oe-init-build-env-memres ~/mybuilds </literallayout> + The OpenEmbedded build system uses the template configuration + files, which are found by default in the + <filename>meta-yocto/conf</filename> directory in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" + section in the Yocto Project Development Manual for more + information. <note> The OpenEmbedded build system does not support file or directory names that contain spaces. |
