| Message ID | 20241022-bug-13225-package-split-v2-1-5715058872f0@bootlin.com |
|---|---|
| State | New |
| Headers | show |
| Series | [v2] overview-manual: concepts: add details on package splitting | expand |
Hi Antonin, On 10/22/24 3:38 PM, Antonin Godard wrote: > The package splitting section of the overview manual currently lacks any > explanation of how package splitting is implemented and redirects to > the package class, which is not really understandable for newcomers to > the project. > > This patch adds a short explanation of what is done: > > * How the PACKAGES variable is defined. > * How the FILES variable is defined. > * How the two work together. > * How to add a custom package. > > This should give enough details to a new user on what package splitting > achieves and how to add a custom package. > > Adresses [YOCTO #13225] > > Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> > --- > Changes in v2: > - Rewrite multiple paragraphs after reviews from Quentin. > - Be explicit on _NOT_ using D in FILES! > - Mention the oe-pkgdata-util cli tool. > - Link to v1: https://lore.kernel.org/r/20241016-bug-13225-package-split-v1-1-20681130d7eb@bootlin.com > --- > documentation/overview-manual/concepts.rst | 61 +++++++++++++++++++++++++++--- > 1 file changed, 56 insertions(+), 5 deletions(-) > > diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst > index 62f2327a7e27a777f738523e7fafe62422186abb..e38ca196260c1f7ece2dcd0cfd3aafe41fd27147 100644 > --- a/documentation/overview-manual/concepts.rst > +++ b/documentation/overview-manual/concepts.rst > @@ -912,11 +912,62 @@ the analysis and package splitting process use several areas: > execute on a system and it generates code for yet another machine > (e.g. :ref:`ref-classes-cross-canadian` recipes). > > -The :term:`FILES` variable defines the > -files that go into each package in > -:term:`PACKAGES`. If you want > -details on how this is accomplished, you can look at > -:yocto_git:`package.bbclass </poky/tree/meta/classes-global/package.bbclass>`. > +Packages for a recipe are listed in the :term:`PACKAGES` variable. The > +:oe_git:`bitbake.conf </openembedded-core/tree/meta/conf/bitbake.conf>` > +configuration file defines the following default list of packages:: > + > + PACKAGES = "${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}" > + > +Each of these packages contain a default list of files defined with the s/contain/contains/ since it's "each" so singular. > +:term:`FILES` variable. For example, the package ``${PN}-dev`` represents files > +useful to the development of applications depending on ``${PN}``. The default > +list of files for ``${PN}-dev``, also defined in :oe_git:`bitbake.conf > +</openembedded-core/tree/meta/conf/bitbake.conf>`, is defined as follows:: > + > + FILES:${PN}-dev = "${includedir} ${FILES_SOLIBSDEV} ${libdir}/*.la \ > + ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \ > + ${datadir}/aclocal ${base_libdir}/*.o \ > + ${libdir}/${BPN}/*.la ${base_libdir}/*.la \ > + ${libdir}/cmake ${datadir}/cmake" > + > +The paths in this list must be *absolute* paths from the point of view of the > +root filesystem on the target, and must *not* make references to the variable I would use the singular here for reference as a path can only make a reference to another path and not multiple ones. > +:term:`D` or any :term:`WORKDIR` related variable. A correct example would be:: > + > + ${sysconfdir}/foo.conf > + > +.. note:: > + > + The list of files for a package is defined using the override syntax by > + separating :term:`FILES` and the package name by a semi-colon (``:``). > + > +.. note:: > + > + To find out which package installs a file, the ``oe-pkgdata-util`` > + command-line utility can be used:: > + > + $ oe-pkgdata-util find-path '/etc/fstab' > + base-files: /etc/fstab > +> + For more information on the ``oe-pkgdata-util`` utility, see the section > + :ref:`dev-manual/debugging:Viewing Package Information with > + \`\`oe-pkgdata-util\`\`` of the Yocto Project Development Tasks Manual. > + I would move the second note to after the paragraph in which the "a file is only in one package" statement below, but that's personal taste at that point :) Looks good to me. With the contain/contains typo fixed: Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de> Cheers, Quentin
On Tue Oct 22, 2024 at 3:47 PM CEST, Quentin Schulz wrote: >> -The :term:`FILES` variable defines the >> -files that go into each package in >> -:term:`PACKAGES`. If you want >> -details on how this is accomplished, you can look at >> -:yocto_git:`package.bbclass </poky/tree/meta/classes-global/package.bbclass>`. >> +Packages for a recipe are listed in the :term:`PACKAGES` variable. The >> +:oe_git:`bitbake.conf </openembedded-core/tree/meta/conf/bitbake.conf>` >> +configuration file defines the following default list of packages:: >> + >> + PACKAGES = "${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}" >> + >> +Each of these packages contain a default list of files defined with the > > s/contain/contains/ since it's "each" so singular. Thanks... I know it's the correct way to write it but my brain can't stop from finding it weird that way :) >> +:term:`FILES` variable. For example, the package ``${PN}-dev`` represents files >> +useful to the development of applications depending on ``${PN}``. The default >> +list of files for ``${PN}-dev``, also defined in :oe_git:`bitbake.conf >> +</openembedded-core/tree/meta/conf/bitbake.conf>`, is defined as follows:: >> + >> + FILES:${PN}-dev = "${includedir} ${FILES_SOLIBSDEV} ${libdir}/*.la \ >> + ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \ >> + ${datadir}/aclocal ${base_libdir}/*.o \ >> + ${libdir}/${BPN}/*.la ${base_libdir}/*.la \ >> + ${libdir}/cmake ${datadir}/cmake" >> + >> +The paths in this list must be *absolute* paths from the point of view of the >> +root filesystem on the target, and must *not* make references to the variable > > I would use the singular here for reference as a path can only make a > reference to another path and not multiple ones. +1 >> +:term:`D` or any :term:`WORKDIR` related variable. A correct example would be:: >> + >> + ${sysconfdir}/foo.conf >> + >> +.. note:: >> + >> + The list of files for a package is defined using the override syntax by >> + separating :term:`FILES` and the package name by a semi-colon (``:``). >> + >> +.. note:: >> + >> + To find out which package installs a file, the ``oe-pkgdata-util`` >> + command-line utility can be used:: >> + >> + $ oe-pkgdata-util find-path '/etc/fstab' >> + base-files: /etc/fstab >> +> + For more information on the ``oe-pkgdata-util`` utility, see the > section >> + :ref:`dev-manual/debugging:Viewing Package Information with >> + \`\`oe-pkgdata-util\`\`` of the Yocto Project Development Tasks Manual. >> + > > I would move the second note to after the paragraph in which the "a file > is only in one package" statement below, but that's personal taste at > that point :) Right, I agree. > Looks good to me. > > With the contain/contains typo fixed: > > Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de> > > Cheers, > Quentin Thanks Quentin. Cheers, Antonin -- Antonin Godard, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst index 62f2327a7e27a777f738523e7fafe62422186abb..e38ca196260c1f7ece2dcd0cfd3aafe41fd27147 100644 --- a/documentation/overview-manual/concepts.rst +++ b/documentation/overview-manual/concepts.rst @@ -912,11 +912,62 @@ the analysis and package splitting process use several areas: execute on a system and it generates code for yet another machine (e.g. :ref:`ref-classes-cross-canadian` recipes). -The :term:`FILES` variable defines the -files that go into each package in -:term:`PACKAGES`. If you want -details on how this is accomplished, you can look at -:yocto_git:`package.bbclass </poky/tree/meta/classes-global/package.bbclass>`. +Packages for a recipe are listed in the :term:`PACKAGES` variable. The +:oe_git:`bitbake.conf </openembedded-core/tree/meta/conf/bitbake.conf>` +configuration file defines the following default list of packages:: + + PACKAGES = "${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}" + +Each of these packages contain a default list of files defined with the +:term:`FILES` variable. For example, the package ``${PN}-dev`` represents files +useful to the development of applications depending on ``${PN}``. The default +list of files for ``${PN}-dev``, also defined in :oe_git:`bitbake.conf +</openembedded-core/tree/meta/conf/bitbake.conf>`, is defined as follows:: + + FILES:${PN}-dev = "${includedir} ${FILES_SOLIBSDEV} ${libdir}/*.la \ + ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \ + ${datadir}/aclocal ${base_libdir}/*.o \ + ${libdir}/${BPN}/*.la ${base_libdir}/*.la \ + ${libdir}/cmake ${datadir}/cmake" + +The paths in this list must be *absolute* paths from the point of view of the +root filesystem on the target, and must *not* make references to the variable +:term:`D` or any :term:`WORKDIR` related variable. A correct example would be:: + + ${sysconfdir}/foo.conf + +.. note:: + + The list of files for a package is defined using the override syntax by + separating :term:`FILES` and the package name by a semi-colon (``:``). + +.. note:: + + To find out which package installs a file, the ``oe-pkgdata-util`` + command-line utility can be used:: + + $ oe-pkgdata-util find-path '/etc/fstab' + base-files: /etc/fstab + + For more information on the ``oe-pkgdata-util`` utility, see the section + :ref:`dev-manual/debugging:Viewing Package Information with + \`\`oe-pkgdata-util\`\`` of the Yocto Project Development Tasks Manual. + +A given file can only ever be in one package. By iterating from the leftmost to +rightmost package in :term:`PACKAGES`, each file matching one of the patterns +defined in the corresponding :term:`FILES` definition is included in the +package. + +To add a custom package variant of the ``${PN}`` recipe named +``${PN}-extra`` (name is arbitrary), one can add it to the +:term:`PACKAGE_BEFORE_PN` variable:: + + PACKAGE_BEFORE_PN += "${PN}-extra" + +Alternatively, a custom package can be added by adding it to the +:term:`PACKAGES` variable using the prepend operator (``=+``):: + + PACKAGES =+ "${PN}-extra" Depending on the type of packages being created (RPM, DEB, or IPK), the :ref:`do_package_write_* <ref-tasks-package_write_deb>`
The package splitting section of the overview manual currently lacks any explanation of how package splitting is implemented and redirects to the package class, which is not really understandable for newcomers to the project. This patch adds a short explanation of what is done: * How the PACKAGES variable is defined. * How the FILES variable is defined. * How the two work together. * How to add a custom package. This should give enough details to a new user on what package splitting achieves and how to add a custom package. Adresses [YOCTO #13225] Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> --- Changes in v2: - Rewrite multiple paragraphs after reviews from Quentin. - Be explicit on _NOT_ using D in FILES! - Mention the oe-pkgdata-util cli tool. - Link to v1: https://lore.kernel.org/r/20241016-bug-13225-package-split-v1-1-20681130d7eb@bootlin.com --- documentation/overview-manual/concepts.rst | 61 +++++++++++++++++++++++++++--- 1 file changed, 56 insertions(+), 5 deletions(-) --- base-commit: e4b64514673471850635a8dbbf62f34e710e276a change-id: 20241015-bug-13225-package-split-57c8dc0f96b5 Best regards,