summaryrefslogtreecommitdiffstats
path: root/documentation/overview-manual/overview-manual-concepts.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/overview-manual/overview-manual-concepts.xml')
-rw-r--r--documentation/overview-manual/overview-manual-concepts.xml391
1 files changed, 0 insertions, 391 deletions
diff --git a/documentation/overview-manual/overview-manual-concepts.xml b/documentation/overview-manual/overview-manual-concepts.xml
index 9f0f9d1d9f..338a190ae2 100644
--- a/documentation/overview-manual/overview-manual-concepts.xml
+++ b/documentation/overview-manual/overview-manual-concepts.xml
@@ -3226,397 +3226,6 @@
3226 articles for background information on Pseudo. 3226 articles for background information on Pseudo.
3227 </para> 3227 </para>
3228 </section> 3228 </section>
3229
3230 <section id="overview-licenses">
3231 <title>Licenses</title>
3232
3233 <para>
3234 This section describes the mechanism by which the
3235 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
3236 tracks changes to licensing text.
3237 The section also describes how to enable commercially licensed
3238 recipes, which by default are disabled.
3239 </para>
3240
3241 <para>
3242 For information that can help you maintain compliance with
3243 various open source licensing during the lifecycle of the product,
3244 see the
3245 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Project's Lifecycle</ulink>"
3246 section in the Yocto Project Development Tasks Manual.
3247 </para>
3248
3249 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
3250 <title>Tracking License Changes</title>
3251
3252 <para>
3253 The license of an upstream project might change in the future.
3254 In order to prevent these changes going unnoticed, the
3255 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
3256 variable tracks changes to the license text. The checksums are
3257 validated at the end of the configure step, and if the
3258 checksums do not match, the build will fail.
3259 </para>
3260
3261 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
3262 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
3263
3264 <para>
3265 The <filename>LIC_FILES_CHKSUM</filename>
3266 variable contains checksums of the license text in the
3267 source code for the recipe.
3268 Following is an example of how to specify
3269 <filename>LIC_FILES_CHKSUM</filename>:
3270 <literallayout class='monospaced'>
3271 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
3272 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
3273 file://licfile2.txt;endline=50;md5=zzzz \
3274 ..."
3275 </literallayout>
3276 <note><title>Notes</title>
3277 <itemizedlist>
3278 <listitem><para>
3279 When using "beginline" and "endline", realize
3280 that line numbering begins with one and not
3281 zero.
3282 Also, the included lines are inclusive (i.e.
3283 lines five through and including 29 in the
3284 previous example for
3285 <filename>licfile1.txt</filename>).
3286 </para></listitem>
3287 <listitem><para>
3288 When a license check fails, the selected license
3289 text is included as part of the QA message.
3290 Using this output, you can determine the exact
3291 start and finish for the needed license text.
3292 </para></listitem>
3293 </itemizedlist>
3294 </note>
3295 </para>
3296
3297 <para>
3298 The build system uses the
3299 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
3300 variable as the default directory when searching files
3301 listed in <filename>LIC_FILES_CHKSUM</filename>.
3302 The previous example employs the default directory.
3303 </para>
3304
3305 <para>
3306 Consider this next example:
3307 <literallayout class='monospaced'>
3308 LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
3309 md5=bb14ed3c4cda583abc85401304b5cd4e"
3310 LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
3311 </literallayout>
3312 </para>
3313
3314 <para>
3315 The first line locates a file in
3316 <filename>${S}/src/ls.c</filename> and isolates lines five
3317 through 16 as license text.
3318 The second line refers to a file in
3319 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
3320 </para>
3321
3322 <para>
3323 Note that <filename>LIC_FILES_CHKSUM</filename> variable is
3324 mandatory for all recipes, unless the
3325 <filename>LICENSE</filename> variable is set to "CLOSED".
3326 </para>
3327 </section>
3328
3329 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
3330 <title>Explanation of Syntax</title>
3331
3332 <para>
3333 As mentioned in the previous section, the
3334 <filename>LIC_FILES_CHKSUM</filename> variable lists all
3335 the important files that contain the license text for the
3336 source code.
3337 It is possible to specify a checksum for an entire file,
3338 or a specific section of a file (specified by beginning and
3339 ending line numbers with the "beginline" and "endline"
3340 parameters, respectively).
3341 The latter is useful for source files with a license
3342 notice header, README documents, and so forth.
3343 If you do not use the "beginline" parameter, then it is
3344 assumed that the text begins on the first line of the file.
3345 Similarly, if you do not use the "endline" parameter,
3346 it is assumed that the license text ends with the last
3347 line of the file.
3348 </para>
3349
3350 <para>
3351 The "md5" parameter stores the md5 checksum of the license
3352 text.
3353 If the license text changes in any way as compared to
3354 this parameter then a mismatch occurs.
3355 This mismatch triggers a build failure and notifies
3356 the developer.
3357 Notification allows the developer to review and address
3358 the license text changes.
3359 Also note that if a mismatch occurs during the build,
3360 the correct md5 checksum is placed in the build log and
3361 can be easily copied to the recipe.
3362 </para>
3363
3364 <para>
3365 There is no limit to how many files you can specify using
3366 the <filename>LIC_FILES_CHKSUM</filename> variable.
3367 Generally, however, every project requires a few
3368 specifications for license tracking.
3369 Many projects have a "COPYING" file that stores the
3370 license information for all the source code files.
3371 This practice allows you to just track the "COPYING"
3372 file as long as it is kept up to date.
3373 <note><title>Tips</title>
3374 <itemizedlist>
3375 <listitem><para>
3376 If you specify an empty or invalid "md5"
3377 parameter,
3378 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
3379 returns an md5 mis-match
3380 error and displays the correct "md5" parameter
3381 value during the build.
3382 The correct parameter is also captured in
3383 the build log.
3384 </para></listitem>
3385 <listitem><para>
3386 If the whole file contains only license text,
3387 you do not need to use the "beginline" and
3388 "endline" parameters.
3389 </para></listitem>
3390 </itemizedlist>
3391 </note>
3392 </para>
3393 </section>
3394 </section>
3395
3396 <section id="enabling-commercially-licensed-recipes">
3397 <title>Enabling Commercially Licensed Recipes</title>
3398
3399 <para>
3400 By default, the OpenEmbedded build system disables
3401 components that have commercial or other special licensing
3402 requirements.
3403 Such requirements are defined on a
3404 recipe-by-recipe basis through the
3405 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
3406 variable definition in the affected recipe.
3407 For instance, the
3408 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
3409 recipe contains the following statement:
3410 <literallayout class='monospaced'>
3411 LICENSE_FLAGS = "commercial"
3412 </literallayout>
3413 Here is a slightly more complicated example that contains both
3414 an explicit recipe name and version (after variable expansion):
3415 <literallayout class='monospaced'>
3416 LICENSE_FLAGS = "license_${PN}_${PV}"
3417 </literallayout>
3418 In order for a component restricted by a
3419 <filename>LICENSE_FLAGS</filename> definition to be enabled and
3420 included in an image, it needs to have a matching entry in the
3421 global
3422 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
3423 variable, which is a variable typically defined in your
3424 <filename>local.conf</filename> file.
3425 For example, to enable the
3426 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
3427 package, you could add either the string
3428 "commercial_gst-plugins-ugly" or the more general string
3429 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
3430 See the
3431 "<link linkend='license-flag-matching'>License Flag Matching</link>"
3432 section for a full
3433 explanation of how <filename>LICENSE_FLAGS</filename> matching
3434 works.
3435 Here is the example:
3436 <literallayout class='monospaced'>
3437 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
3438 </literallayout>
3439 Likewise, to additionally enable the package built from the
3440 recipe containing
3441 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>,
3442 and assuming that the actual recipe name was
3443 <filename>emgd_1.10.bb</filename>, the following string would
3444 enable that package as well as the original
3445 <filename>gst-plugins-ugly</filename> package:
3446 <literallayout class='monospaced'>
3447 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
3448 </literallayout>
3449 As a convenience, you do not need to specify the complete
3450 license string in the whitelist for every package.
3451 You can use an abbreviated form, which consists
3452 of just the first portion or portions of the license
3453 string before the initial underscore character or characters.
3454 A partial string will match any license that contains the
3455 given string as the first portion of its license.
3456 For example, the following whitelist string will also match
3457 both of the packages previously mentioned as well as any other
3458 packages that have licenses starting with "commercial" or
3459 "license".
3460 <literallayout class='monospaced'>
3461 LICENSE_FLAGS_WHITELIST = "commercial license"
3462 </literallayout>
3463 </para>
3464
3465 <section id="license-flag-matching">
3466 <title>License Flag Matching</title>
3467
3468 <para>
3469 License flag matching allows you to control what recipes
3470 the OpenEmbedded build system includes in the build.
3471 Fundamentally, the build system attempts to match
3472 <filename>LICENSE_FLAGS</filename> strings found in recipes
3473 against <filename>LICENSE_FLAGS_WHITELIST</filename>
3474 strings found in the whitelist.
3475 A match causes the build system to include a recipe in the
3476 build, while failure to find a match causes the build
3477 system to exclude a recipe.
3478 </para>
3479
3480 <para>
3481 In general, license flag matching is simple.
3482 However, understanding some concepts will help you
3483 correctly and effectively use matching.
3484 </para>
3485
3486 <para>
3487 Before a flag
3488 defined by a particular recipe is tested against the
3489 contents of the whitelist, the expanded string
3490 <filename>_${PN}</filename> is appended to the flag.
3491 This expansion makes each
3492 <filename>LICENSE_FLAGS</filename> value recipe-specific.
3493 After expansion, the string is then matched against the
3494 whitelist.
3495 Thus, specifying
3496 <filename>LICENSE_FLAGS = "commercial"</filename>
3497 in recipe "foo", for example, results in the string
3498 <filename>"commercial_foo"</filename>.
3499 And, to create a match, that string must appear in the
3500 whitelist.
3501 </para>
3502
3503 <para>
3504 Judicious use of the <filename>LICENSE_FLAGS</filename>
3505 strings and the contents of the
3506 <filename>LICENSE_FLAGS_WHITELIST</filename> variable
3507 allows you a lot of flexibility for including or excluding
3508 recipes based on licensing.
3509 For example, you can broaden the matching capabilities by
3510 using license flags string subsets in the whitelist.
3511 <note>
3512 When using a string subset, be sure to use the part of
3513 the expanded string that precedes the appended
3514 underscore character (e.g.
3515 <filename>usethispart_1.3</filename>,
3516 <filename>usethispart_1.4</filename>, and so forth).
3517 </note>
3518 For example, simply specifying the string "commercial" in
3519 the whitelist matches any expanded
3520 <filename>LICENSE_FLAGS</filename> definition that starts
3521 with the string "commercial" such as "commercial_foo" and
3522 "commercial_bar", which are the strings the build system
3523 automatically generates for hypothetical recipes named
3524 "foo" and "bar" assuming those recipes simply specify the
3525 following:
3526 <literallayout class='monospaced'>
3527 LICENSE_FLAGS = "commercial"
3528 </literallayout>
3529 Thus, you can choose to exhaustively
3530 enumerate each license flag in the whitelist and
3531 allow only specific recipes into the image, or
3532 you can use a string subset that causes a broader range of
3533 matches to allow a range of recipes into the image.
3534 </para>
3535
3536 <para>
3537 This scheme works even if the
3538 <filename>LICENSE_FLAGS</filename> string already
3539 has <filename>_${PN}</filename> appended.
3540 For example, the build system turns the license flag
3541 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and
3542 would match both the general "commercial" and the specific
3543 "commercial_1.2_foo" strings found in the whitelist, as
3544 expected.
3545 </para>
3546
3547 <para>
3548 Here are some other scenarios:
3549 <itemizedlist>
3550 <listitem><para>
3551 You can specify a versioned string in the recipe
3552 such as "commercial_foo_1.2" in a "foo" recipe.
3553 The build system expands this string to
3554 "commercial_foo_1.2_foo".
3555 Combine this license flag with a whitelist that has
3556 the string "commercial" and you match the flag
3557 along with any other flag that starts with the
3558 string "commercial".
3559 </para></listitem>
3560 <listitem><para>
3561 Under the same circumstances, you can use
3562 "commercial_foo" in the whitelist and the build
3563 system not only matches "commercial_foo_1.2" but
3564 also matches any license flag with the string
3565 "commercial_foo", regardless of the version.
3566 </para></listitem>
3567 <listitem><para>
3568 You can be very specific and use both the
3569 package and version parts in the whitelist (e.g.
3570 "commercial_foo_1.2") to specifically match a
3571 versioned recipe.
3572 </para></listitem>
3573 </itemizedlist>
3574 </para>
3575 </section>
3576
3577 <section id="other-variables-related-to-commercial-licenses">
3578 <title>Other Variables Related to Commercial Licenses</title>
3579
3580 <para>
3581 Other helpful variables related to commercial
3582 license handling exist and are defined in the
3583 <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
3584 <literallayout class='monospaced'>
3585 COMMERCIAL_AUDIO_PLUGINS ?= ""
3586 COMMERCIAL_VIDEO_PLUGINS ?= ""
3587 </literallayout>
3588 If you want to enable these components, you can do so by
3589 making sure you have statements similar to the following
3590 in your <filename>local.conf</filename> configuration file:
3591 <literallayout class='monospaced'>
3592 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
3593 gst-plugins-ugly-mpegaudioparse"
3594 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
3595 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
3596 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
3597 </literallayout>
3598 Of course, you could also create a matching whitelist
3599 for those components using the more general "commercial"
3600 in the whitelist, but that would also enable all the
3601 other packages with <filename>LICENSE_FLAGS</filename>
3602 containing "commercial", which you may or may not want:
3603 <literallayout class='monospaced'>
3604 LICENSE_FLAGS_WHITELIST = "commercial"
3605 </literallayout>
3606 </para>
3607
3608 <para>
3609 Specifying audio and video plug-ins as part of the
3610 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
3611 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
3612 (along with the enabling
3613 <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
3614 plug-ins or components into built images, thus adding
3615 support for media formats or components.
3616 </para>
3617 </section>
3618 </section>
3619 </section>
3620</chapter> 3229</chapter>
3621<!-- 3230<!--
3622vim: expandtab tw=80 ts=4 3231vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-11 11:12:16 +0000