summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/technical-details.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/technical-details.xml')
-rw-r--r--documentation/ref-manual/technical-details.xml357
1 files changed, 0 insertions, 357 deletions
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index ba0b27ddc9..3827366dcb 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -13,363 +13,6 @@
13 x32, Wayland support, and Licenses. 13 x32, Wayland support, and Licenses.
14 </para> 14 </para>
15 15
16<section id="licenses">
17 <title>Licenses</title>
18
19 <para>
20 This section describes the mechanism by which the OpenEmbedded build system
21 tracks changes to licensing text.
22 The section also describes how to enable commercially licensed recipes,
23 which by default are disabled.
24 </para>
25
26 <para>
27 For information that can help you maintain compliance with various open
28 source licensing during the lifecycle of the product, see the
29 "<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>"
30 section in the Yocto Project Development Tasks Manual.
31 </para>
32
33 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
34 <title>Tracking License Changes</title>
35
36 <para>
37 The license of an upstream project might change in the future.
38 In order to prevent these changes going unnoticed, the
39 <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
40 variable tracks changes to the license text. The checksums are validated at the end of the
41 configure step, and if the checksums do not match, the build will fail.
42 </para>
43
44 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
45 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
46
47 <para>
48 The <filename>LIC_FILES_CHKSUM</filename>
49 variable contains checksums of the license text in the source
50 code for the recipe.
51 Following is an example of how to specify
52 <filename>LIC_FILES_CHKSUM</filename>:
53 <literallayout class='monospaced'>
54 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
55 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
56 file://licfile2.txt;endline=50;md5=zzzz \
57 ..."
58 </literallayout>
59 <note><title>Notes</title>
60 <itemizedlist>
61 <listitem><para>
62 When using "beginline" and "endline", realize that
63 line numbering begins with one and not zero.
64 Also, the included lines are inclusive (i.e. lines
65 five through and including 29 in the previous
66 example for <filename>licfile1.txt</filename>).
67 </para></listitem>
68 <listitem><para>
69 When a license check fails, the selected license
70 text is included as part of the QA message.
71 Using this output, you can determine the exact
72 start and finish for the needed license text.
73 </para></listitem>
74 </itemizedlist>
75 </note>
76 </para>
77
78 <para>
79 The build system uses the
80 <filename><link linkend='var-S'>S</link></filename> variable as
81 the default directory when searching files listed in
82 <filename>LIC_FILES_CHKSUM</filename>.
83 The previous example employs the default directory.
84 </para>
85
86 <para>
87 Consider this next example:
88 <literallayout class='monospaced'>
89 LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
90 md5=bb14ed3c4cda583abc85401304b5cd4e"
91 LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
92 </literallayout>
93 </para>
94
95 <para>
96 The first line locates a file in
97 <filename>${S}/src/ls.c</filename> and isolates lines five
98 through 16 as license text.
99 The second line refers to a file in
100 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
101 </para>
102 <para>
103 Note that <filename>LIC_FILES_CHKSUM</filename> variable is
104 mandatory for all recipes, unless the
105 <filename>LICENSE</filename> variable is set to "CLOSED".
106 </para>
107 </section>
108
109 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
110 <title>Explanation of Syntax</title>
111 <para>
112 As mentioned in the previous section, the
113 <filename>LIC_FILES_CHKSUM</filename> variable lists all the
114 important files that contain the license text for the source code.
115 It is possible to specify a checksum for an entire file, or a specific section of a
116 file (specified by beginning and ending line numbers with the "beginline" and "endline"
117 parameters, respectively).
118 The latter is useful for source files with a license notice header,
119 README documents, and so forth.
120 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
121 first line of the file.
122 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
123 ends with the last line of the file.
124 </para>
125
126 <para>
127 The "md5" parameter stores the md5 checksum of the license text.
128 If the license text changes in any way as compared to this parameter
129 then a mismatch occurs.
130 This mismatch triggers a build failure and notifies the developer.
131 Notification allows the developer to review and address the license text changes.
132 Also note that if a mismatch occurs during the build, the correct md5
133 checksum is placed in the build log and can be easily copied to the recipe.
134 </para>
135
136 <para>
137 There is no limit to how many files you can specify using the
138 <filename>LIC_FILES_CHKSUM</filename> variable.
139 Generally, however, every project requires a few specifications for license tracking.
140 Many projects have a "COPYING" file that stores the license information for all the source
141 code files.
142 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
143 </para>
144
145 <tip>
146 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
147 error and displays the correct "md5" parameter value during the build.
148 The correct parameter is also captured in the build log.
149 </tip>
150
151 <tip>
152 If the whole file contains only license text, you do not need to use the "beginline" and
153 "endline" parameters.
154 </tip>
155 </section>
156 </section>
157
158 <section id="enabling-commercially-licensed-recipes">
159 <title>Enabling Commercially Licensed Recipes</title>
160
161 <para>
162 By default, the OpenEmbedded build system disables
163 components that have commercial or other special licensing
164 requirements.
165 Such requirements are defined on a
166 recipe-by-recipe basis through the
167 <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
168 variable definition in the affected recipe.
169 For instance, the
170 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
171 recipe contains the following statement:
172 <literallayout class='monospaced'>
173 LICENSE_FLAGS = "commercial"
174 </literallayout>
175 Here is a slightly more complicated example that contains both an
176 explicit recipe name and version (after variable expansion):
177 <literallayout class='monospaced'>
178 LICENSE_FLAGS = "license_${PN}_${PV}"
179 </literallayout>
180 In order for a component restricted by a <filename>LICENSE_FLAGS</filename>
181 definition to be enabled and included in an image, it
182 needs to have a matching entry in the global
183 <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
184 variable, which is a variable
185 typically defined in your <filename>local.conf</filename> file.
186 For example, to enable
187 the <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
188 package, you could add either the string
189 "commercial_gst-plugins-ugly" or the more general string
190 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
191 See the
192 "<link linkend='license-flag-matching'>License Flag Matching</link>" section
193 for a full explanation of how <filename>LICENSE_FLAGS</filename> matching works.
194 Here is the example:
195 <literallayout class='monospaced'>
196 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
197 </literallayout>
198 Likewise, to additionally enable the package built from the recipe containing
199 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, and assuming
200 that the actual recipe name was <filename>emgd_1.10.bb</filename>,
201 the following string would enable that package as well as
202 the original <filename>gst-plugins-ugly</filename> package:
203 <literallayout class='monospaced'>
204 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
205 </literallayout>
206 As a convenience, you do not need to specify the complete license string
207 in the whitelist for every package.
208 You can use an abbreviated form, which consists
209 of just the first portion or portions of the license string before
210 the initial underscore character or characters.
211 A partial string will match
212 any license that contains the given string as the first
213 portion of its license.
214 For example, the following
215 whitelist string will also match both of the packages
216 previously mentioned as well as any other packages that have
217 licenses starting with "commercial" or "license".
218 <literallayout class='monospaced'>
219 LICENSE_FLAGS_WHITELIST = "commercial license"
220 </literallayout>
221 </para>
222
223 <section id="license-flag-matching">
224 <title>License Flag Matching</title>
225
226 <para>
227 License flag matching allows you to control what recipes the
228 OpenEmbedded build system includes in the build.
229 Fundamentally, the build system attempts to match
230 <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
231 strings found in recipes against
232 <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
233 strings found in the whitelist.
234 A match causes the build system to include a recipe in the
235 build, while failure to find a match causes the build system to
236 exclude a recipe.
237 </para>
238
239 <para>
240 In general, license flag matching is simple.
241 However, understanding some concepts will help you
242 correctly and effectively use matching.
243 </para>
244
245 <para>
246 Before a flag
247 defined by a particular recipe is tested against the
248 contents of the whitelist, the expanded string
249 <filename>_${PN}</filename> is appended to the flag.
250 This expansion makes each <filename>LICENSE_FLAGS</filename>
251 value recipe-specific.
252 After expansion, the string is then matched against the
253 whitelist.
254 Thus, specifying
255 <filename>LICENSE_FLAGS = "commercial"</filename>
256 in recipe "foo", for example, results in the string
257 <filename>"commercial_foo"</filename>.
258 And, to create a match, that string must appear in the
259 whitelist.
260 </para>
261
262 <para>
263 Judicious use of the <filename>LICENSE_FLAGS</filename>
264 strings and the contents of the
265 <filename>LICENSE_FLAGS_WHITELIST</filename> variable
266 allows you a lot of flexibility for including or excluding
267 recipes based on licensing.
268 For example, you can broaden the matching capabilities by
269 using license flags string subsets in the whitelist.
270 <note>When using a string subset, be sure to use the part of
271 the expanded string that precedes the appended underscore
272 character (e.g. <filename>usethispart_1.3</filename>,
273 <filename>usethispart_1.4</filename>, and so forth).
274 </note>
275 For example, simply specifying the string "commercial" in
276 the whitelist matches any expanded
277 <filename>LICENSE_FLAGS</filename> definition that starts with
278 the string "commercial" such as "commercial_foo" and
279 "commercial_bar", which are the strings the build system
280 automatically generates for hypothetical recipes named
281 "foo" and "bar" assuming those recipes simply specify the
282 following:
283 <literallayout class='monospaced'>
284 LICENSE_FLAGS = "commercial"
285 </literallayout>
286 Thus, you can choose to exhaustively
287 enumerate each license flag in the whitelist and
288 allow only specific recipes into the image, or
289 you can use a string subset that causes a broader range of
290 matches to allow a range of recipes into the image.
291 </para>
292
293 <para>
294 This scheme works even if the
295 <filename>LICENSE_FLAGS</filename> string already
296 has <filename>_${PN}</filename> appended.
297 For example, the build system turns the license flag
298 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would
299 match both the general "commercial" and the specific
300 "commercial_1.2_foo" strings found in the whitelist, as
301 expected.
302 </para>
303
304 <para>
305 Here are some other scenarios:
306 <itemizedlist>
307 <listitem><para>You can specify a versioned string in the
308 recipe such as "commercial_foo_1.2" in a "foo" recipe.
309 The build system expands this string to
310 "commercial_foo_1.2_foo".
311 Combine this license flag with a whitelist that has
312 the string "commercial" and you match the flag along
313 with any other flag that starts with the string
314 "commercial".</para></listitem>
315 <listitem><para>Under the same circumstances, you can
316 use "commercial_foo" in the whitelist and the
317 build system not only matches "commercial_foo_1.2" but
318 also matches any license flag with the string
319 "commercial_foo", regardless of the version.
320 </para></listitem>
321 <listitem><para>You can be very specific and use both the
322 package and version parts in the whitelist (e.g.
323 "commercial_foo_1.2") to specifically match a
324 versioned recipe.</para></listitem>
325 </itemizedlist>
326 </para>
327 </section>
328
329 <section id="other-variables-related-to-commercial-licenses">
330 <title>Other Variables Related to Commercial Licenses</title>
331
332 <para>
333 Other helpful variables related to commercial
334 license handling exist and are defined in the
335 <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
336 <literallayout class='monospaced'>
337 COMMERCIAL_AUDIO_PLUGINS ?= ""
338 COMMERCIAL_VIDEO_PLUGINS ?= ""
339 </literallayout>
340 If you want to enable these components, you can do so by making sure you have
341 statements similar to the following
342 in your <filename>local.conf</filename> configuration file:
343 <literallayout class='monospaced'>
344 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
345 gst-plugins-ugly-mpegaudioparse"
346 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
347 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
348 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
349 </literallayout>
350 Of course, you could also create a matching whitelist
351 for those components using the more general "commercial"
352 in the whitelist, but that would also enable all the
353 other packages with
354 <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
355 containing "commercial", which you may or may not want:
356 <literallayout class='monospaced'>
357 LICENSE_FLAGS_WHITELIST = "commercial"
358 </literallayout>
359 </para>
360
361 <para>
362 Specifying audio and video plug-ins as part of the
363 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
364 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
365 (along with the enabling
366 <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
367 plug-ins or components into built images, thus adding
368 support for media formats or components.
369 </para>
370 </section>
371 </section>
372</section>
373</chapter> 16</chapter>
374<!-- 17<!--
375vim: expandtab tw=80 ts=4 18vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-15 11:45:37 +0000