From ed0a240e1632682ec4c33341f3e24ad71773cdfc Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 11 Dec 2012 12:07:58 -0600 Subject: documentation: Rename of poky-ref-manual folder to ref-manual. Changing the folder that holds the YP Reference Manual to be "ref-manual". This will help with confustion over the manual's intended purpose. (From yocto-docs rev: 1106442964b5080cb0b6b3bd3af32e9407c0f7c1) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/technical-details.xml | 1011 ++++++++++++++++++++++++ 1 file changed, 1011 insertions(+) create mode 100644 documentation/ref-manual/technical-details.xml (limited to 'documentation/ref-manual/technical-details.xml') diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml new file mode 100644 index 0000000000..b1d7c40799 --- /dev/null +++ b/documentation/ref-manual/technical-details.xml @@ -0,0 +1,1011 @@ + %poky; ] > + + +Technical Details + + + This chapter provides technical details for various parts of the Yocto Project. + Currently, topics include Yocto Project components and shared state (sstate) cache. + + +
+ Yocto Project Components + + + The BitBake task executor together with various types of configuration files form the + OpenEmbedded Core. + This section overviews the BitBake task executor and the + configuration files by describing what they are used for and how they interact. + + + + BitBake handles the parsing and execution of the data files. + The data itself is of various types: + + Recipes: Provides details about particular + pieces of software + Class Data: An abstraction of common build + information (e.g. how to build a Linux kernel). + Configuration Data: Defines machine-specific settings, + policy decisions, etc. + Configuration data acts as the glue to bind everything together. + + For more information on data, see the + "Yocto Project Terms" + section in the Yocto Project Development Manual. + + + + BitBake knows how to combine multiple data sources together and refers to each data source + as a layer. + For information on layers, see the + "Understanding and + Creating Layers" section of the Yocto Project Development Manual. + + + + Following are some brief details on these core components. + For more detailed information on these components see the + "Directory Structure" chapter. + + +
+ BitBake + + + BitBake is the tool at the heart of the OpenEmbedded build system and is responsible + for parsing the metadata, generating a list of tasks from it, + and then executing those tasks. + To see a list of the options BitBake supports, use the following help command: + + $ bitbake --help + + + + + The most common usage for BitBake is bitbake <packagename>, where + packagename is the name of the package you want to build + (referred to as the "target" in this manual). + The target often equates to the first part of a .bb filename. + So, to run the matchbox-desktop_1.2.3.bb file, you + might type the following: + + $ bitbake matchbox-desktop + + Several different versions of matchbox-desktop might exist. + BitBake chooses the one selected by the distribution configuration. + You can get more details about how BitBake chooses between different + target versions and providers in the + "Preferences and Providers" section. + + + + BitBake also tries to execute any dependent tasks first. + So for example, before building matchbox-desktop, BitBake + would build a cross compiler and eglibc if they had not already + been built. + This release of the Yocto Project does not support the glibc + GNU version of the Unix standard C library. By default, the OpenEmbedded build system + builds with eglibc. + + + + A useful BitBake option to consider is the -k or + --continue option. + This option instructs BitBake to try and continue processing the job as much + as possible even after encountering an error. + When an error occurs, the target that + failed and those that depend on it cannot be remade. + However, when you use this option other dependencies can still be processed. + +
+ +
+ Metadata (Recipes) + + + The .bb files are usually referred to as "recipes." + In general, a recipe contains information about a single piece of software. + The information includes the location from which to download the source patches + (if any are needed), which special configuration options to apply, + how to compile the source files, and how to package the compiled output. + + + + The term "package" can also be used to describe recipes. + However, since the same word is used for the packaged output from the OpenEmbedded + build system (i.e. .ipk or .deb files), + this document avoids using the term "package" when referring to recipes. + +
+ +
+ Classes + + + Class files (.bbclass) contain information that is useful to share + between metadata files. + An example is the Autotools class, which contains + common settings for any application that Autotools uses. + The "Classes" chapter provides details + about common classes and how to use them. + +
+ +
+ Configuration + + + The configuration files (.conf) define various configuration variables + that govern the OpenEmbedded build process. + These files fall into several areas that define machine configuration options, + distribution configuration options, compiler tuning options, general common configuration + options and user configuration options (local.conf, which is found + in the Build Directory). + +
+
+ +
+ Shared State Cache + + + By design, the OpenEmbedded build system builds everything from scratch unless + BitBake can determine that parts don't need to be rebuilt. + Fundamentally, building from scratch is attractive as it means all parts are + built fresh and there is no possibility of stale data causing problems. + When developers hit problems, they typically default back to building from scratch + so they know the state of things from the start. + + + + Building an image from scratch is both an advantage and a disadvantage to the process. + As mentioned in the previous paragraph, building from scratch ensures that + everything is current and starts from a known state. + However, building from scratch also takes much longer as it generally means + rebuilding things that don't necessarily need rebuilt. + + + + The Yocto Project implements shared state code that supports incremental builds. + The implementation of the shared state code answers the following questions that + were fundamental roadblocks within the OpenEmbedded incremental build support system: + + What pieces of the system have changed and what pieces have not changed? + How are changed pieces of software removed and replaced? + How are pre-built components that don't need to be rebuilt from scratch + used when they are available? + + + + + For the first question, the build system detects changes in the "inputs" to a given task by + creating a checksum (or signature) of the task's inputs. + If the checksum changes, the system assumes the inputs have changed and the task needs to be + rerun. + For the second question, the shared state (sstate) code tracks which tasks add which output + to the build process. + This means the output from a given task can be removed, upgraded or otherwise manipulated. + The third question is partly addressed by the solution for the second question + assuming the build system can fetch the sstate objects from remote locations and + install them if they are deemed to be valid. + + + + The rest of this section goes into detail about the overall incremental build + architecture, the checksums (signatures), shared state, and some tips and tricks. + + +
+ Overall Architecture + + + When determining what parts of the system need to be built, BitBake + uses a per-task basis and does not use a per-recipe basis. + You might wonder why using a per-task basis is preferred over a per-recipe basis. + To help explain, consider having the IPK packaging backend enabled and then switching to DEB. + In this case, do_install and do_package + output are still valid. + However, with a per-recipe approach, the build would not include the + .deb files. + Consequently, you would have to invalidate the whole build and rerun it. + Rerunning everything is not the best situation. + Also in this case, the core must be "taught" much about specific tasks. + This methodology does not scale well and does not allow users to easily add new tasks + in layers or as external recipes without touching the packaged-staging core. + +
+ +
+ Checksums (Signatures) + + + The shared state code uses a checksum, which is a unique signature of a task's + inputs, to determine if a task needs to be run again. + Because it is a change in a task's inputs that triggers a rerun, the process + needs to detect all the inputs to a given task. + For shell tasks, this turns out to be fairly easy because + the build process generates a "run" shell script for each task and + it is possible to create a checksum that gives you a good idea of when + the task's data changes. + + + + To complicate the problem, there are things that should not be included in + the checksum. + First, there is the actual specific build path of a given task - + the WORKDIR. + It does not matter if the working directory changes because it should not + affect the output for target packages. + Also, the build process has the objective of making native/cross packages relocatable. + The checksum therefore needs to exclude WORKDIR. + The simplistic approach for excluding the working directory is to set + WORKDIR to some fixed value and create the checksum + for the "run" script. + + + + Another problem results from the "run" scripts containing functions that + might or might not get called. + The incremental build solution contains code that figures out dependencies + between shell functions. + This code is used to prune the "run" scripts down to the minimum set, + thereby alleviating this problem and making the "run" scripts much more + readable as a bonus. + + + + So far we have solutions for shell scripts. + What about python tasks? + The same approach applies even though these tasks are more difficult. + The process needs to figure out what variables a python function accesses + and what functions it calls. + Again, the incremental build solution contains code that first figures out + the variable and function dependencies, and then creates a checksum for the data + used as the input to the task. + + + + Like the WORKDIR case, situations exist where dependencies + should be ignored. + For these cases, you can instruct the build process to ignore a dependency + by using a line like the following: + + PACKAGE_ARCHS[vardepsexclude] = "MACHINE" + + This example ensures that the PACKAGE_ARCHS variable does not + depend on the value of MACHINE, even if it does reference it. + + + + Equally, there are cases where we need to add dependencies BitBake is not able to find. + You can accomplish this by using a line like the following: + + PACKAGE_ARCHS[vardeps] = "MACHINE" + + This example explicitly adds the MACHINE variable as a + dependency for PACKAGE_ARCHS. + + + + Consider a case with inline python, for example, where BitBake is not + able to figure out dependencies. + When running in debug mode (i.e. using -DDD), BitBake + produces output when it discovers something for which it cannot figure out + dependencies. + The Yocto Project team has currently not managed to cover those dependencies + in detail and is aware of the need to fix this situation. + + + + Thus far, this section has limited discussion to the direct inputs into a task. + Information based on direct inputs is referred to as the "basehash" in the + code. + However, there is still the question of a task's indirect inputs - the + things that were already built and present in the Build Directory. + The checksum (or signature) for a particular task needs to add the hashes + of all the tasks on which the particular task depends. + Choosing which dependencies to add is a policy decision. + However, the effect is to generate a master checksum that combines the basehash + and the hashes of the task's dependencies. + + + + At the code level, there are a variety of ways both the basehash and the + dependent task hashes can be influenced. + Within the BitBake configuration file, we can give BitBake some extra information + to help it construct the basehash. + The following statements effectively result in a list of global variable + dependency excludes - variables never included in any checksum: + + BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH" + BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS" + BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER" + BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET" + + The previous example actually excludes + WORKDIR + since it is actually constructed as a path within + TMPDIR, which is on + the whitelist. + + + + The rules for deciding which hashes of dependent tasks to include through + dependency chains are more complex and are generally accomplished with a + python function. + The code in meta/lib/oe/sstatesig.py shows two examples + of this and also illustrates how you can insert your own policy into the system + if so desired. + This file defines the two basic signature generators OE-Core + uses: "OEBasic" and "OEBasicHash". + By default, there is a dummy "noop" signature handler enabled in BitBake. + This means that behavior is unchanged from previous versions. + OE-Core uses the "OEBasic" signature handler by default + through this setting in the bitbake.conf file: + + BB_SIGNATURE_HANDLER ?= "OEBasic" + + The "OEBasicHash" BB_SIGNATURE_HANDLER is the same as the + "OEBasic" version but adds the task hash to the stamp files. + This results in any metadata change that changes the task hash, automatically + causing the task to be run again. + This removes the need to bump PR + values and changes to metadata automatically ripple across the build. + Currently, this behavior is not the default behavior for OE-Core + but is the default in poky. + + + + It is also worth noting that the end result of these signature generators is to + make some dependency and hash information available to the build. + This information includes: + + BB_BASEHASH_task-<taskname> - the base hashes for each task in the recipe + BB_BASEHASH_<filename:taskname> - the base hashes for each dependent task + BBHASHDEPS_<filename:taskname> - The task dependencies for each task + BB_TASKHASH - the hash of the currently running task + + +
+ +
+ Shared State + + + Checksums and dependencies, as discussed in the previous section, solve half the + problem. + The other part of the problem is being able to use checksum information during the build + and being able to reuse or rebuild specific components. + + + + The shared state class (sstate.bbclass) + is a relatively generic implementation of how to "capture" a snapshot of a given task. + The idea is that the build process does not care about the source of a task's output. + Output could be freshly built or it could be downloaded and unpacked from + somewhere - the build process doesn't need to worry about its source. + + + + There are two types of output, one is just about creating a directory + in WORKDIR. + A good example is the output of either do_install or + do_package. + The other type of output occurs when a set of data is merged into a shared directory + tree such as the sysroot. + + + + The Yocto Project team has tried to keep the details of the implementation hidden in + sstate.bbclass. + From a user's perspective, adding shared state wrapping to a task + is as simple as this do_deploy example taken from + do_deploy.bbclass: + + DEPLOYDIR = "${WORKDIR}/deploy-${PN}" + SSTATETASKS += "do_deploy" + do_deploy[sstate-name] = "deploy" + do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" + do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" + + python do_deploy_setscene () { + sstate_setscene(d) + } + addtask do_deploy_setscene + + In the example, we add some extra flags to the task, a name field ("deploy"), an + input directory where the task sends data, and the output + directory where the data from the task should eventually be copied. + We also add a _setscene variant of the task and add the task + name to the SSTATETASKS list. + + + + If you have a directory whose contents you need to preserve, you can do this with + a line like the following: + + do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" + + This method, as well as the following example, also works for multiple directories. + + do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" + do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" + do_package[sstate-lockfile] = "${PACKAGELOCK}" + + These methods also include the ability to take a lockfile when manipulating + shared state directory structures since some cases are sensitive to file + additions or removals. + + + + Behind the scenes, the shared state code works by looking in + SSTATE_DIR and + SSTATE_MIRRORS + for shared state files. + Here is an example: + + SSTATE_MIRRORS ?= "\ + file://.* http://someserver.tld/share/sstate/PATH \n \ + file://.* file:///some/local/dir/sstate/PATH" + + + The shared state directory (SSTATE_DIR) is + organized into two-character subdirectories, where the subdirectory + names are based on the first two characters of the hash. + If the shared state directory structure for a mirror has the + same structure as SSTATE_DIR, you must + specify "PATH" as part of the URI to enable the build system + to map to the appropriate subdirectory. + + + + + The shared state package validity can be detected just by looking at the + filename since the filename contains the task checksum (or signature) as + described earlier in this section. + If a valid shared state package is found, the build process downloads it + and uses it to accelerate the task. + + + + The build processes uses the *_setscene tasks + for the task acceleration phase. + BitBake goes through this phase before the main execution code and tries + to accelerate any tasks for which it can find shared state packages. + If a shared state package for a task is available, the shared state + package is used. + This means the task and any tasks on which it is dependent are not + executed. + + + + As a real world example, the aim is when building an IPK-based image, + only the do_package_write_ipk tasks would have their + shared state packages fetched and extracted. + Since the sysroot is not used, it would never get extracted. + This is another reason why a task-based approach is preferred over a + recipe-based approach, which would have to install the output from every task. + +
+ +
+ Tips and Tricks + + + The code in the build system that supports incremental builds is not + simple code. + This section presents some tips and tricks that help you work around + issues related to shared state code. + + +
+ Debugging + + + When things go wrong, debugging needs to be straightforward. + Because of this, the Yocto Project team included strong debugging + tools: + + Whenever a shared state package is written out, so is a + corresponding .siginfo file. + This practice results in a pickled python database of all + the metadata that went into creating the hash for a given shared state + package. + If BitBake is run with the --dump-signatures + (or -S) option, BitBake dumps out + .siginfo files in + the stamp directory for every task it would have executed instead of + building the specified target package. + There is a bitbake-diffsigs command that + can process these .siginfo files. + If one file is specified, it will dump out the dependency + information in the file. + If two files are specified, it will compare the two files and dump out + the differences between the two. + This allows the question of "What changed between X and Y?" to be + answered easily. + + +
+ +
+ Invalidating Shared State + + + The shared state code uses checksums and shared state + cache to avoid unnecessarily rebuilding tasks. + As with all schemes, this one has some drawbacks. + It is possible that you could make implicit changes that are not factored + into the checksum calculation, but do affect a task's output. + A good example is perhaps when a tool changes its output. + Let's say that the output of rpmdeps needed to change. + The result of the change should be that all the "package", "package_write_rpm", + and "package_deploy-rpm" shared state cache items would become invalid. + But, because this is a change that is external to the code and therefore implicit, + the associated shared state cache items do not become invalidated. + In this case, the build process would use the cached items rather than running the + task again. + Obviously, these types of implicit changes can cause problems. + + + + To avoid these problems during the build, you need to understand the effects of any + change you make. + Note that any changes you make directly to a function automatically are factored into + the checksum calculation and thus, will invalidate the associated area of sstate cache. + You need to be aware of any implicit changes that are not obvious changes to the + code and could affect the output of a given task. + Once you are aware of such a change, you can take steps to invalidate the cache + and force the task to run. + The step to take is as simple as changing a function's comments in the source code. + For example, to invalidate package shared state files, change the comment statements + of do_package or the comments of one of the functions it calls. + The change is purely cosmetic, but it causes the checksum to be recalculated and + forces the task to be run again. + + + + For an example of a commit that makes a cosmetic change to invalidate + a shared state, see this + commit. + +
+
+
+ +
+ x32 + + + x32 is a new processor-specific Application Binary Interface (psABI) for x86_64. + An ABI defines the calling conventions between functions in a processing environment. + The interface determines what registers are used and what the sizes are for various C data types. + + + + Some processing environments prefer using 32-bit applications even when running + on Intel 64-bit platforms. + Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms. + The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources, + leaving the system underutilized. + Now consider the x86_64 psABI. + This ABI is newer and uses 64-bits for data sizes and program pointers. + The extra bits increase the footprint size of the programs, libraries, + and also increases the memory and file system size requirements. + Executing under the x32 psABI enables user programs to utilize CPU and system resources + more efficiently while keeping the memory footprint of the applications low. + Extra bits are used for registers but not for addressing mechanisms. + + +
+ Support + + + While the x32 psABI specifications are not fully finalized, this Yocto Project + release supports current development specifications of x32 psABI. + As of this release of the Yocto Project, x32 psABI support exists as follows: + + You can create packages and images in x32 psABI format on x86_64 architecture targets. + + You can use the x32 psABI support through the meta-x32 + layer on top of the OE-core/Yocto layer. + The toolchain from the experimental/meta-x32 layer + is used for building x32 psABI program binaries. + You can successfully build many recipes with the x32 toolchain. + You can create and boot core-image-minimal and + core-image-sato images. + + +
+ +
+ Future Development and Limitations + + + As of this Yocto Project release, the x32 psABI kernel and library interfaces + specifications are not finalized. + + + + Future Plans for the x32 psABI in the Yocto Project include the following: + + Enhance and fix the few remaining recipes so they + work with and support x32 toolchains. + Enhance RPM Package Manager (RPM) support for x32 binaries. + Support larger images. + Integrate x32 recipes, toolchain, and kernel changes from + experimental/meta-x32 into OE-core. + + +
+ +
+ Using x32 Right Now + + + Despite the fact the x32 psABI support is in development state for this release of the + Yocto Project, you can follow these steps to use the x32 spABI: + + Add the experimental/meta-x32 layer to your local + Build Directory. + You can find the experimental/meta-x32 source repository at + . + Edit your conf/bblayers.conf file so that it includes + the meta-x32. + Here is an example: + + BBLAYERS ?= " \ + /home/nitin/prj/poky.git/meta \ + /home/nitin/prj/poky.git/meta-yocto \ + /home/nitin/prj/poky.git/meta-yocto-bsp \ + /home/nitin/prj/meta-x32.git \ + " + BBLAYERS_NON_REMOVABLE ?= " \ + /home/nitin/prj/poky.git/meta \ + /home/nitin/prj/poky.git/meta-yocto \ + " + + Enable the x32 psABI tuning file for x86_64 + machines by editing the conf/local.conf like this: + + MACHINE = "qemux86-64" + DEFAULTTUNE = "x86-64-x32" + baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \ + or 'INVALID'), True) or 'lib'}" + #MACHINE = "atom-pc" + #DEFAULTTUNE = "core2-64-x32" + + As usual, use BitBake to build an image that supports the x32 psABI. + Here is an example: + + $ bitake core-image-sato + + As usual, run your image using QEMU: + + $ runqemu qemux86-64 core-image-sato + + + +
+
+ +
+ Licenses + + + This section describes the mechanism by which the OpenEmbedded build system + tracks changes to licensing text. + The section also describes how to enable commercially licensed recipes, + which by default are disabled. + + + + For information that can help you maintain compliance with various open + source licensing during the lifecycle of the product, see the + "Maintaining Open Source License Compliance During Your Project's Lifecycle" section + in the Yocto Project Development Manual. + + +
+ Tracking License Changes + + + The license of an upstream project might change in the future. + In order to prevent these changes going unnoticed, the + LIC_FILES_CHKSUM + variable tracks changes to the license text. The checksums are validated at the end of the + configure step, and if the checksums do not match, the build will fail. + + +
+ Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable + + + The LIC_FILES_CHKSUM + variable contains checksums of the license text in the source code for the recipe. + Following is an example of how to specify LIC_FILES_CHKSUM: + + LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ + file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ + file://licfile2.txt;endline=50;md5=zzzz \ + ..." + + + + + The build system uses the + S variable as the + default directory used when searching files listed in + LIC_FILES_CHKSUM. + The previous example employs the default directory. + + + + You can also use relative paths as shown in the following example: + + LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ + md5=bb14ed3c4cda583abc85401304b5cd4e" + LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" + + + + + In this example, the first line locates a file in + ${S}/src/ls.c. + The second line refers to a file in + WORKDIR, which is the parent + of S. + + + Note that this variable is mandatory for all recipes, unless the + LICENSE variable is set to "CLOSED". + +
+ +
+ Explanation of Syntax + + As mentioned in the previous section, the + LIC_FILES_CHKSUM variable lists all the + important files that contain the license text for the source code. + It is possible to specify a checksum for an entire file, or a specific section of a + file (specified by beginning and ending line numbers with the "beginline" and "endline" + parameters, respectively). + The latter is useful for source files with a license notice header, + README documents, and so forth. + If you do not use the "beginline" parameter, then it is assumed that the text begins on the + first line of the file. + Similarly, if you do not use the "endline" parameter, it is assumed that the license text + ends with the last line of the file. + + + + The "md5" parameter stores the md5 checksum of the license text. + If the license text changes in any way as compared to this parameter + then a mismatch occurs. + This mismatch triggers a build failure and notifies the developer. + Notification allows the developer to review and address the license text changes. + Also note that if a mismatch occurs during the build, the correct md5 + checksum is placed in the build log and can be easily copied to the recipe. + + + + There is no limit to how many files you can specify using the + LIC_FILES_CHKSUM variable. + Generally, however, every project requires a few specifications for license tracking. + Many projects have a "COPYING" file that stores the license information for all the source + code files. + This practice allows you to just track the "COPYING" file as long as it is kept up to date. + + + + If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match + error and displays the correct "md5" parameter value during the build. + The correct parameter is also captured in the build log. + + + + If the whole file contains only license text, you do not need to use the "beginline" and + "endline" parameters. + +
+
+ +
+ Enabling Commercially Licensed Recipes + + + By default, the OpenEmbedded build system disables + components that have commercial or other special licensing + requirements. + Such requirements are defined on a + recipe-by-recipe basis through the LICENSE_FLAGS variable + definition in the affected recipe. + For instance, the + $HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly + recipe contains the following statement: + + LICENSE_FLAGS = "commercial" + + Here is a slightly more complicated example that contains both an + explicit recipe name and version (after variable expansion): + + LICENSE_FLAGS = "license_${PN}_${PV}" + + In order for a component restricted by a LICENSE_FLAGS + definition to be enabled and included in an image, it + needs to have a matching entry in the global + LICENSE_FLAGS_WHITELIST variable, which is a variable + typically defined in your local.conf file. + For example, to enable + the $HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly + package, you could add either the string + "commercial_gst-plugins-ugly" or the more general string + "commercial" to LICENSE_FLAGS_WHITELIST. + See the + "License Flag Matching" section + for a full explanation of how LICENSE_FLAGS matching works. + Here is the example: + + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" + + Likewise, to additionally enable the package built from the recipe containing + LICENSE_FLAGS = "license_${PN}_${PV}", and assuming + that the actual recipe name was emgd_1.10.bb, + the following string would enable that package as well as + the original gst-plugins-ugly package: + + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" + + As a convenience, you do not need to specify the complete license string + in the whitelist for every package. + you can use an abbreviated form, which consists + of just the first portion or portions of the license string before + the initial underscore character or characters. + A partial string will match + any license that contains the given string as the first + portion of its license. + For example, the following + whitelist string will also match both of the packages + previously mentioned as well as any other packages that have + licenses starting with "commercial" or "license". + + LICENSE_FLAGS_WHITELIST = "commercial license" + + + +
+ License Flag Matching + + + The definition of 'matching' in reference to a + recipe's LICENSE_FLAGS setting is simple. + However, some things exist that you should know about in order to + correctly and effectively use it. + + + + Before a flag + defined by a particular recipe is tested against the + contents of the LICENSE_FLAGS_WHITELIST variable, the + string _${PN} (with + PN expanded of course) is + appended to the flag, thus automatically making each + LICENSE_FLAGS value recipe-specific. + That string is + then matched against the whitelist. + So if you specify LICENSE_FLAGS = "commercial" in recipe + "foo" for example, the string "commercial_foo" + would normally be what is specified in the whitelist in order for it to + match. + + + + You can broaden the match by + putting any "_"-separated beginning subset of a + LICENSE_FLAGS flag in the whitelist, which will also + match. + For example, simply specifying "commercial" in + the whitelist would match any expanded LICENSE_FLAGS + definition starting with "commercial" such as + "commercial_foo" and "commercial_bar", which are the + strings that would be automatically generated for + hypothetical "foo" and "bar" recipes assuming those + recipes had simply specified the following: + + LICENSE_FLAGS = "commercial" + + + + + Broadening the match allows for a range of specificity for the items + in the whitelist, from more general to perfectly + specific. + So you have the choice of exhaustively + enumerating each license flag in the whitelist to + allow only those specific recipes into the image, or + of using a more general string to pick up anything + matching just the first component or components of the specified + string. + + + + This scheme works even if the flag already + has _${PN} appended - the extra _${PN} is + redundant, but does not affect the outcome. + For example, a license flag of "commercial_1.2_foo" would + turn into "commercial_1.2_foo_foo" and would match + both the general "commercial" and the specific + "commercial_1.2_foo", as expected. + The flag would also match + "commercial_1.2_foo_foo" and "commercial_1.2", which + does not make much sense regarding use in the whitelist. + + + + For a versioned string, you could instead specify + "commercial_foo_1.2", which would turn into + "commercial_foo_1.2_foo". + And, as expected, this flag allows + you to pick up this package along with + anything else "commercial" when you specify "commercial" + in the whitelist. + Or, the flag allows you to pick up this package along with anything "commercial_foo" + regardless of version when you use "commercial_foo" in the whitelist. + Finally, you can be completely specific about the package and version and specify + "commercial_foo_1.2" package and version. + +
+ + +
+
+ + -- cgit v1.2.3-54-g00ecf