From 8753c6b2888cbe64760800cba1e55e4ce53309d2 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 11 Dec 2012 12:24:29 -0600 Subject: Documentation: ref-manual - removing old poky-ref-manual files Removed the old poky-ref-manuals from the new ref-manual structure. (From yocto-docs rev: b5db4ddea205875ed3acacb90f46efd557337e0d) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../poky-ref-manual/technical-details.xml | 1011 -------------------- 1 file changed, 1011 deletions(-) delete mode 100644 documentation/poky-ref-manual/technical-details.xml (limited to 'documentation/poky-ref-manual/technical-details.xml') diff --git a/documentation/poky-ref-manual/technical-details.xml b/documentation/poky-ref-manual/technical-details.xml deleted file mode 100644 index b1d7c40799..0000000000 --- a/documentation/poky-ref-manual/technical-details.xml +++ /dev/null @@ -1,1011 +0,0 @@ - %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