From 84ee8c653a45ffbda1fd3773f5fbb67d20d1bfc3 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 2 Jun 2014 15:22:28 +0300 Subject: [PATCH] ref-manual, dev-manual: Updates for custom template configuration directory. Fixes [YOCTO #5895] I created a new section in the dev-manual titles "Creating a Custom Template Configuration Directory" that describes how the build system uses the template local.conf and bblayers.conf and conf-notes.txt files as a basis when creating the real deals in the build directory's conf folder. The context of this is so that the user can create their own directory with their own template files for repeated configurations and to create a custom conf-notes.txt file should they want the setup scripts to display some custom list of targets. I also modified the two script references in the ref-manual for oe-init-build-env and oe-init-build-env-memres. I needed to link to the "how-to" section and added a bit in there about how the scripts go about forming the conf files in the build directory. (From yocto-docs rev: c07fb7082fe08387bbc546b2a23620dedc7127b8) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 113 ++++++++++++++++++ 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 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 @@ +
+ Creating a Custom Template Configuration Directory + + + You might find yourself repeating the same configurations for + a particular build or group of builds. + If so, rather than repeatedly editing your + local.conf and possibly your + bblayers.conf, 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. + + + + The OpenEmbedded build system uses the environment variable + TEMPLATECONF to point to the directory + from which it gathers configuration information that ultimately + ends up in the + Build Directory's + conf directory. + By default, TEMPLATECONF points here: + + TEMPLATECONF=${TEMPLATECONF:-meta-yocto/conf} + + 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 + bblayers.conf.sample, + local.conf.sample, and + site.conf.sample configuration files. + The build system uses these files to form the respective + bblayers.conf, + local.conf, and the + site.conf configuration files it places in + the conf directory with the + Build Directory. + + + + To override these default configuration files with + configurations you want used with every build, simply point the + TEMPLATECONF to your directory. + The TEMPLATECONF variable is set in the + .templateconf file, which is in the + top-level + Source Directory + folder (e.g. poky). + Edit the .templateconf 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 + meta-mylayer located in your home directory + and you want your template configuration directory named + myconf. + Changing the .templateconf as follows + causes the OpenEmbedded build system to look in your directory + and base its configuration files on the + *.sample configuration files it finds. + The final configuration files (i.e. + local.conf and + bblayers.conf ultimately still end up in + your Build Directory, but they are based on your + *.sample files. + + TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf} + + + + + Aside from the *.sample configuration files, + the conf-notes.txt also resides in the + default meta-yocto/conf directory. + The scripts that set up the build environment + (i.e. + &OE_INIT_FILE; + and + oe-init-build-env-memres) + use this file to display BitBake targets as part of the script + output. + Customizing this conf-notes.txt file is a + good way to make sure your list of custom targets appears + as part of the script's output. + + + + Here is output from either of the setup scripts by default: + + $ 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 + + + + + Changing the listed common targets is as easy as editing your + version of conf-notes.txt in your + custom template configuration directory and making sure you + have TEMPLATECONF pointing to it. + +
+
Customizing Images 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 @@ 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 + "Creating a Custom Template Configuration Directory" + section in the Yocto Project Development Manual for more + information. @@ -258,6 +260,14 @@ $ source &OE_INIT_FILE; ~/mybuilds + The OpenEmbedded build system uses the template configuration + files, which are found by default in the + meta-yocto/conf directory in the + Source Directory. + See the + "Creating a Custom Template Configuration Directory" + section in the Yocto Project Development Manual for more + information. 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 + "Creating a Custom Template Configuration Directory" + section in the Yocto Project Development Manual for more + information. @@ -368,6 +380,14 @@ $ source oe-init-build-env-memres ~/mybuilds + The OpenEmbedded build system uses the template configuration + files, which are found by default in the + meta-yocto/conf directory in the + Source Directory. + See the + "Creating a Custom Template Configuration Directory" + section in the Yocto Project Development Manual for more + information. The OpenEmbedded build system does not support file or directory names that contain spaces.