diff options
author | Michael Opdenacker <michael.opdenacker@bootlin.com> | 2023-08-09 16:24:23 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2023-08-30 15:54:59 +0100 |
commit | 8a00ac35dea568cf6b9c669448422d72ef589e97 (patch) | |
tree | cea6990f1eed7eef1d4e1cef4dcf1dd9aea8f2ca | |
parent | 80d1c907e6b32f717eef9cd00733f582864e2e91 (diff) | |
download | poky-8a00ac35dea568cf6b9c669448422d72ef589e97.tar.gz |
contributor-guide: add recipe style guide
(From yocto-docs rev: a61a7677adb9bf22dc0d28e72a8fedf2df27e80a)
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/contributor-guide/index.rst | 1 | ||||
-rw-r--r-- | documentation/contributor-guide/recipe-style-guide.rst | 263 | ||||
-rw-r--r-- | documentation/dev-manual/new-recipe.rst | 54 |
3 files changed, 268 insertions, 50 deletions
diff --git a/documentation/contributor-guide/index.rst b/documentation/contributor-guide/index.rst index d723854843..7a39f994e2 100644 --- a/documentation/contributor-guide/index.rst +++ b/documentation/contributor-guide/index.rst | |||
@@ -20,6 +20,7 @@ this. | |||
20 | 20 | ||
21 | identify-component | 21 | identify-component |
22 | submit-defect | 22 | submit-defect |
23 | recipe-style-guide | ||
23 | submit-change | 24 | submit-change |
24 | 25 | ||
25 | .. include:: /boilerplate.rst | 26 | .. include:: /boilerplate.rst |
diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst new file mode 100644 index 0000000000..5210062802 --- /dev/null +++ b/documentation/contributor-guide/recipe-style-guide.rst | |||
@@ -0,0 +1,263 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | Recipe Style Guide | ||
4 | ****************** | ||
5 | |||
6 | Recipe Naming Conventions | ||
7 | ========================= | ||
8 | |||
9 | In general, most recipes should follow the naming convention | ||
10 | ``recipes-category/package/packagename_version.bb``. Recipes for related | ||
11 | projects may share the same package directory. ``packagename``, ``category``, | ||
12 | and ``package`` may contain hyphens, but hyphens are not allowed in ``version``. | ||
13 | |||
14 | If the recipe is tracking a Git revision that does not correspond to a released | ||
15 | version of the software, ``version`` may be ``git`` (e.g. ``packagename_git.bb``) | ||
16 | |||
17 | Version Policy | ||
18 | ============== | ||
19 | |||
20 | Our versions follow the form ``<package epoch>:<package version>-<package revision>`` | ||
21 | or in BitBake variable terms ${:term:`PE`}:${:term:`PV`}-${:term:`PR`}. We | ||
22 | generally follow the `Debian <https://www.debian.org/doc/debian-policy/ch-controlfields.html#version>`__ | ||
23 | version policy which defines these terms. | ||
24 | |||
25 | In most cases the version :term:`PV` will be set automatically from the recipe | ||
26 | file name. It is recommended to use released versions of software as these are | ||
27 | revisions that upstream are expecting people to use. | ||
28 | |||
29 | Package versions should always compare and sort correctly so that upgrades work | ||
30 | as expected. With conventional versions such as ``1.4`` upgrading ``to 1.5`` | ||
31 | this happens naturally, but some versions don't sort. For example, | ||
32 | ``1.5 Release Candidate 2`` could be written as ``1.5rc2`` but this sorts after | ||
33 | ``1.5``, so upgrades from feeds won't happen correctly. | ||
34 | |||
35 | Instead the tilde (``~``) operator can be used, which sorts before the empty | ||
36 | string so ``1.5~rc2`` comes before ``1.5``. There is a historical syntax which | ||
37 | may be found where :term:`PV` is set as a combination of the prior version | ||
38 | ``+`` the pre-release version, for example ``PV=1.4+1.5rc2``. This is a valid | ||
39 | syntax but the tilde form is preferred. | ||
40 | |||
41 | For version comparisons, the ``opkg-compare-versions`` program from | ||
42 | ``opkg-utils`` can be useful when attempting to determine how two version | ||
43 | numbers compare to each other. Our definitive version comparison algorithm is | ||
44 | the one within bitbake which aims to match those of the package managers and | ||
45 | Debian policy closely. | ||
46 | |||
47 | When a recipe references a git revision that does not correspond to a released | ||
48 | version of software (e.g. is not a tagged version), the :term:`PV` variable | ||
49 | should include the Git revision using the following to make the | ||
50 | version clear:: | ||
51 | |||
52 | PV = "<version>+git${SRCPV}" | ||
53 | |||
54 | In this case, ``<version>`` should be the most recently released version of the | ||
55 | software from the current source revision (``git describe`` can be useful for | ||
56 | determining this). Whilst not recommended for published layers, this format is | ||
57 | also useful when using :term:`AUTOREV` to set the recipe to increment source | ||
58 | control revisions automatically, which can be useful during local development. | ||
59 | |||
60 | Version Number Changes | ||
61 | ====================== | ||
62 | |||
63 | The :term:`PR` variable is used to indicate different revisions of a recipe | ||
64 | that reference the same upstream source version. It can be used to force a | ||
65 | new version of a package to be installed onto a device from a package feed. | ||
66 | These once had to be set manually but in most cases these can now be set and | ||
67 | incremented automatically by a PR Server connected with a package feed. | ||
68 | |||
69 | When :term:`PV` increases, any existing :term:`PR` value can and should be | ||
70 | removed. | ||
71 | |||
72 | If :term:`PV` changes in such a way that it does not increase with respect to | ||
73 | the previous value, you need to increase :term:`PE` to ensure package managers | ||
74 | will upgrade it correctly. If unset you should set :term:`PE` to "1" since | ||
75 | the default of empty is easily confused with "0" depending on the package | ||
76 | manager. :term:`PE` can only have an integer value. | ||
77 | |||
78 | Recipe formatting | ||
79 | ================= | ||
80 | |||
81 | Variable Formatting | ||
82 | ------------------- | ||
83 | |||
84 | - Variable assignment should a space around each side of the operator, e.g. | ||
85 | ``FOO = "bar"``, not ``FOO="bar"``. | ||
86 | |||
87 | - Double quotes should be used on the right-hand side of the assignment, | ||
88 | e.g. ``FOO = "bar"`` not ``FOO = 'bar'`` | ||
89 | |||
90 | - Spaces should be used for indenting variables, with 4 spaces per tab | ||
91 | |||
92 | - Long variables should be split over multiple lines when possible by using | ||
93 | the continuation character (``\``) | ||
94 | |||
95 | - When splitting a long variable over multiple lines, all continuation lines | ||
96 | should be indented (with spaces) to align with the start of the quote on the | ||
97 | first line:: | ||
98 | |||
99 | FOO = "this line is \ | ||
100 | long \ | ||
101 | " | ||
102 | |||
103 | Instead of:: | ||
104 | |||
105 | FOO = "this line is \ | ||
106 | long \ | ||
107 | " | ||
108 | |||
109 | Python Function formatting | ||
110 | -------------------------- | ||
111 | |||
112 | - Spaces must be used for indenting Python code, with 4 spaces per tab | ||
113 | |||
114 | Shell Function formatting | ||
115 | ------------------------- | ||
116 | |||
117 | - The formatting of shell functions should be consistent within layers. | ||
118 | Some use tabs, some use spaces. | ||
119 | |||
120 | Recipe metadata | ||
121 | =============== | ||
122 | |||
123 | Required Variables | ||
124 | ------------------ | ||
125 | |||
126 | The following variables should be included in all recipes: | ||
127 | |||
128 | - :term:`SUMMARY`: a one line description of the upstream project | ||
129 | |||
130 | - :term:`DESCRIPTION`: an extended description of the upstream project, | ||
131 | possibly with multiple lines. If no reasonable description can be written, | ||
132 | this may be omitted as it defaults to :term:`SUMMARY`. | ||
133 | |||
134 | - :term:`HOMEPAGE`: the URL to the upstream projects homepage. | ||
135 | |||
136 | - :term:`BUGTRACKER`: the URL upstream projects bug tracking website, | ||
137 | if applicable. | ||
138 | |||
139 | Recipe Ordering | ||
140 | --------------- | ||
141 | |||
142 | When a variable is defined in recipes and classes, variables should follow the | ||
143 | general order when possible: | ||
144 | |||
145 | - :term:`SUMMARY` | ||
146 | - :term:`DESCRIPTION` | ||
147 | - :term:`AUTHOR` | ||
148 | - :term:`HOMEPAGE` | ||
149 | - :term:`BUGTRACKER` | ||
150 | - :term:`SECTION` | ||
151 | - :term:`LICENSE` | ||
152 | - :term:`LIC_FILES_CHKSUM` | ||
153 | - :term:`DEPENDS` | ||
154 | - :term:`PROVIDES` | ||
155 | - :term:`PV` | ||
156 | - :term:`SRC_URI` | ||
157 | - :term:`SRCREV` | ||
158 | - :term:`S` | ||
159 | - ``inherit ...`` | ||
160 | - :term:`PACKAGECONFIG` | ||
161 | - Build class specific variables such as ``EXTRA_QMAKEVARS_POST`` and :term:`EXTRA_OECONF` | ||
162 | - Tasks such as :ref:`ref-tasks-configure` | ||
163 | - :term:`PACKAGE_ARCH` | ||
164 | - :term:`PACKAGES` | ||
165 | - :term:`FILES` | ||
166 | - :term:`RDEPENDS` | ||
167 | - :term:`RRECOMMENDS` | ||
168 | - :term:`RSUGGESTS` | ||
169 | - :term:`RPROVIDES` | ||
170 | - :term:`RCONFLICTS` | ||
171 | - :term:`BBCLASSEXTEND` | ||
172 | |||
173 | There are some cases where ordering is important and these cases would override | ||
174 | this default order. Examples include: | ||
175 | |||
176 | - :term:`PACKAGE_ARCH` needing to be set before ``inherit packagegroup`` | ||
177 | |||
178 | Tasks should be ordered based on the order they generally execute. For commonly | ||
179 | used tasks this would be: | ||
180 | |||
181 | - :ref:`ref-tasks-fetch` | ||
182 | - :ref:`ref-tasks-unpack` | ||
183 | - :ref:`ref-tasks-patch` | ||
184 | - :ref:`ref-tasks-prepare_recipe_sysroot` | ||
185 | - :ref:`ref-tasks-configure` | ||
186 | - :ref:`ref-tasks-compile` | ||
187 | - :ref:`ref-tasks-install` | ||
188 | - :ref:`ref-tasks-populate_sysroot` | ||
189 | - :ref:`ref-tasks-package` | ||
190 | |||
191 | Custom tasks should be sorted similarly. | ||
192 | |||
193 | Package specific variables are typically grouped together, e.g.:: | ||
194 | |||
195 | RDEPENDS:${PN} = “foo” | ||
196 | RDEPENDS:${PN}-libs = “bar” | ||
197 | |||
198 | RRECOMMENDS:${PN} = “one” | ||
199 | RRECOMMENDS:${PN}-libs = “two” | ||
200 | |||
201 | Recipe License Fields | ||
202 | --------------------- | ||
203 | |||
204 | Recipes need to define both the :term:`LICENSE` and | ||
205 | :term:`LIC_FILES_CHKSUM` variables: | ||
206 | |||
207 | - :term:`LICENSE`: This variable specifies the license for the software. | ||
208 | If you do not know the license under which the software you are | ||
209 | building is distributed, you should go to the source code and look | ||
210 | for that information. Typical files containing this information | ||
211 | include ``COPYING``, :term:`LICENSE`, and ``README`` files. You could | ||
212 | also find the information near the top of a source file. For example, | ||
213 | given a piece of software licensed under the GNU General Public | ||
214 | License version 2, you would set :term:`LICENSE` as follows:: | ||
215 | |||
216 | LICENSE = "GPL-2.0-only" | ||
217 | |||
218 | The licenses you specify within :term:`LICENSE` can have any name as long | ||
219 | as you do not use spaces, since spaces are used as separators between | ||
220 | license names. For standard licenses, use the names of the files in | ||
221 | ``meta/files/common-licenses/`` or the :term:`SPDXLICENSEMAP` flag names | ||
222 | defined in ``meta/conf/licenses.conf``. | ||
223 | |||
224 | - :term:`LIC_FILES_CHKSUM`: The OpenEmbedded build system uses this | ||
225 | variable to make sure the license text has not changed. If it has, | ||
226 | the build produces an error and it affords you the chance to figure | ||
227 | it out and correct the problem. | ||
228 | |||
229 | You need to specify all applicable licensing files for the software. | ||
230 | At the end of the configuration step, the build process will compare | ||
231 | the checksums of the files to be sure the text has not changed. Any | ||
232 | differences result in an error with the message containing the | ||
233 | current checksum. For more explanation and examples of how to set the | ||
234 | :term:`LIC_FILES_CHKSUM` variable, see the | ||
235 | ":ref:`dev-manual/licenses:tracking license changes`" section. | ||
236 | |||
237 | To determine the correct checksum string, you can list the | ||
238 | appropriate files in the :term:`LIC_FILES_CHKSUM` variable with incorrect | ||
239 | md5 strings, attempt to build the software, and then note the | ||
240 | resulting error messages that will report the correct md5 strings. | ||
241 | See the ":ref:`dev-manual/new-recipe:fetching code`" section for | ||
242 | additional information. | ||
243 | |||
244 | Here is an example that assumes the software has a ``COPYING`` file:: | ||
245 | |||
246 | LIC_FILES_CHKSUM = "file://COPYING;md5=xxx" | ||
247 | |||
248 | When you try to build the | ||
249 | software, the build system will produce an error and give you the | ||
250 | correct string that you can substitute into the recipe file for a | ||
251 | subsequent build. | ||
252 | |||
253 | Tips and Guidelines for Writing Recipes | ||
254 | --------------------------------------- | ||
255 | |||
256 | - Use :term:`BBCLASSEXTEND` instead of creating separate recipes such as ``-native`` | ||
257 | and ``-nativesdk`` ones, whenever possible. This avoids having to maintain multiple | ||
258 | recipe files at the same time. | ||
259 | |||
260 | - Avoid manually mangling ``pkg-config`` ``.pc`` files. | ||
261 | Recipes using ``pkg-config`` should use variables to ensure they are correctly | ||
262 | relocatable and not need manual path correction in the recipe. | ||
263 | |||
diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst index af390773a9..cb9533ff5d 100644 --- a/documentation/dev-manual/new-recipe.rst +++ b/documentation/dev-manual/new-recipe.rst | |||
@@ -432,56 +432,10 @@ named the same as the base name of the recipe | |||
432 | Licensing | 432 | Licensing |
433 | ========= | 433 | ========= |
434 | 434 | ||
435 | Your recipe needs to have both the | 435 | Your recipe needs to define variables related to the license |
436 | :term:`LICENSE` and | 436 | under whith the software is distributed. See the |
437 | :term:`LIC_FILES_CHKSUM` | 437 | :ref:`contributor-guide/recipe-style-guide:recipe license fields` |
438 | variables: | 438 | section in the Contributor Guide for details. |
439 | |||
440 | - :term:`LICENSE`: This variable specifies the license for the software. | ||
441 | If you do not know the license under which the software you are | ||
442 | building is distributed, you should go to the source code and look | ||
443 | for that information. Typical files containing this information | ||
444 | include ``COPYING``, :term:`LICENSE`, and ``README`` files. You could | ||
445 | also find the information near the top of a source file. For example, | ||
446 | given a piece of software licensed under the GNU General Public | ||
447 | License version 2, you would set :term:`LICENSE` as follows:: | ||
448 | |||
449 | LICENSE = "GPL-2.0-only" | ||
450 | |||
451 | The licenses you specify within :term:`LICENSE` can have any name as long | ||
452 | as you do not use spaces, since spaces are used as separators between | ||
453 | license names. For standard licenses, use the names of the files in | ||
454 | ``meta/files/common-licenses/`` or the :term:`SPDXLICENSEMAP` flag names | ||
455 | defined in ``meta/conf/licenses.conf``. | ||
456 | |||
457 | - :term:`LIC_FILES_CHKSUM`: The OpenEmbedded build system uses this | ||
458 | variable to make sure the license text has not changed. If it has, | ||
459 | the build produces an error and it affords you the chance to figure | ||
460 | it out and correct the problem. | ||
461 | |||
462 | You need to specify all applicable licensing files for the software. | ||
463 | At the end of the configuration step, the build process will compare | ||
464 | the checksums of the files to be sure the text has not changed. Any | ||
465 | differences result in an error with the message containing the | ||
466 | current checksum. For more explanation and examples of how to set the | ||
467 | :term:`LIC_FILES_CHKSUM` variable, see the | ||
468 | ":ref:`dev-manual/licenses:tracking license changes`" section. | ||
469 | |||
470 | To determine the correct checksum string, you can list the | ||
471 | appropriate files in the :term:`LIC_FILES_CHKSUM` variable with incorrect | ||
472 | md5 strings, attempt to build the software, and then note the | ||
473 | resulting error messages that will report the correct md5 strings. | ||
474 | See the ":ref:`dev-manual/new-recipe:fetching code`" section for | ||
475 | additional information. | ||
476 | |||
477 | Here is an example that assumes the software has a ``COPYING`` file:: | ||
478 | |||
479 | LIC_FILES_CHKSUM = "file://COPYING;md5=xxx" | ||
480 | |||
481 | When you try to build the | ||
482 | software, the build system will produce an error and give you the | ||
483 | correct string that you can substitute into the recipe file for a | ||
484 | subsequent build. | ||
485 | 439 | ||
486 | Dependencies | 440 | Dependencies |
487 | ============ | 441 | ============ |