[1/2,YOCTO,#13270] Refactor the docbook-xml recipe to use docbook.org packages rather than hacked up debian package

---
 .../docbook-xml/docbook-xml-dtd4_4.5.bb       | 74 ++++++++++++-------
 1 file changed, 49 insertions(+), 25 deletions(-)

-- 
2.34.1

Please squash the two commits into one.

Alex



On Sun, 19 Feb 2023 at 22:38, Richard Elberger <rich@richelberger.com> wrote:
>
> ---
>  .../docbook-xml/docbook-xml-dtd4_4.5.bb       | 74 ++++++++++++-------
>  1 file changed, 49 insertions(+), 25 deletions(-)
>
> diff --git a/meta/recipes-devtools/docbook-xml/docbook-xml-dtd4_4.5.bb b/meta/recipes-devtools/docbook-xml/docbook-xml-dtd4_4.5.bb
> index 2bec1442af..71aa8c14ec 100644
> --- a/meta/recipes-devtools/docbook-xml/docbook-xml-dtd4_4.5.bb
> +++ b/meta/recipes-devtools/docbook-xml/docbook-xml-dtd4_4.5.bb
> @@ -1,30 +1,54 @@
>  SUMMARY = "Document type definitions for verification of XML data files"
>  DESCRIPTION = "Document type definitions for verification of XML data \
> -files against the DocBook rule set, it ships with the latest DocBook 4.5 \
> -XML DTD, as well as a selected set of legacy DTDs for use with older \
> -documents, including 4.0, 4.1.2, 4.2, 4.3 and 4.4"
> -HOMEPAGE = "http://www.docbook.org/xml/"
> +files against the DocBook rule set."
> +HOMEPAGE = "https://docbook.org"
>
> -LICENSE = "OASIS"
> -LIC_FILES_CHKSUM = "file://${WORKDIR}/LICENSE-OASIS;md5=c608985dd5f7f215e669e7639a0b1d2e"
> +inherit allarch
> +BBCLASSEXTEND = "native"
>
> -# Note: the upstream sources are not distributed with a license file.
> -# LICENSE-OASIS is included as a "patch" to workaround this. When
> -# upgrading this recipe, please verify whether this is still needed.
> -SRC_URI = "http://snapshot.debian.org/archive/debian/20160728T043443Z/pool/main/d/docbook-xml/docbook-xml_${PV}.orig.tar.gz \
> -           file://LICENSE-OASIS \
> -           file://docbook-xml-update-catalog.xml.patch \
> -"
> +# To support apps with xml schema backward compatibility, we must
> +# install a set of schemas. Install the latest based on PV and then
> +# name any specific versions as required. TODO: Figure out a mechanism
> +# to filter exactly which versions are necessary, if that's even
> +# possible.
> +#
> +# DocBook.org lists available packages at https://docbook.org/xml/
> +#
> +# These packages are available as source but it requires the ability
> +# to use the Gradle build system to do so. It might be safer to use
> +# the source tree which would also enable proper SBOM generation
> +# through the bitbake build system. https://github.com/docbook/docbook
> +#
>
> -SRC_URI[md5sum] = "487b4d44e15cffb1f4048af23f98208e"
> -SRC_URI[sha256sum] = "b0f8edcf697f5318e63dd98c9a931f3fee167af0805ba441db372e0f17b2a44f"
> +S = "${WORKDIR}"
>
> -UPSTREAM_CHECK_URI = "${DEBIAN_MIRROR}/main/d/docbook-xml/"
> +SRC_URI += "https://docbook.org/xml/4.1.2/docbkx412.zip;name=payload412;subdir=docbook-xml-4.1.2"
> +SRC_URI[payload412.md5sum] = "900d7609fb7e6d78901b357e4acfbc17"
> +SRC_URI[payload412.sha256sum] = "30f0644064e0ea71751438251940b1431f46acada814a062870f486c772e7772"
>
> -S = "${WORKDIR}/docbook-xml-4.5.c31424"
> +SRC_URI += "https://docbook.org/xml/4.2/docbook-xml-4.2.zip;name=payload42;subdir=docbook-xml-4.2"
> +SRC_URI[payload42.md5sum] = "73fe50dfe74ca631c1602f558ed8961f"
> +SRC_URI[payload42.sha256sum] = "acc4601e4f97a196076b7e64b368d9248b07c7abf26b34a02cca40eeebe60fa2"
>
> -inherit allarch
> -BBCLASSEXTEND = "native"
> +SRC_URI += "https://docbook.org/xml/4.3/docbook-xml-4.3.zip;name=payload43;subdir=docbook-xml-4.3"
> +SRC_URI[payload43.md5sum] = "ab200202b9e136a144db1e0864c45074"
> +SRC_URI[payload43.sha256sum] = "23068a94ea6fd484b004c5a73ec36a66aa47ea8f0d6b62cc1695931f5c143464"
> +
> +SRC_URI += "https://docbook.org/xml/4.4/docbook-xml-4.4.zip;name=payload44;subdir=docbook-xml-4.4"
> +SRC_URI[payload44.md5sum] = "cbb04e9a700955d88c50962ef22c1634"
> +SRC_URI[payload44.sha256sum] = "02f159eb88c4254d95e831c51c144b1863b216d909b5ff45743a1ce6f5273090"
> +
> +SRC_URI += "https://docbook.org/xml/${PV}/docbook-xml-${PV}.zip;name=payloadPV;subdir=docbook-xml-${PV}"
> +SRC_URI[payloadPV.md5sum] = "03083e288e87a7e829e437358da7ef9e"
> +SRC_URI[payloadPV.sha256sum] = "4e4e037a2b83c98c6c94818390d4bdd3f6e10f6ec62dd79188594e26190dc7b4"
> +
> +# The upstream sources are not distributed with a license file.
> +# LICENSE-OASIS is included as a "patch" to workaround this. When
> +# upgrading this recipe, please verify whether this is still needed.
> +
> +LICENSE = "OASIS"
> +LIC_FILES_CHKSUM = "file://${WORKDIR}/LICENSE-OASIS;md5=c608985dd5f7f215e669e7639a0b1d2e"
> +SRC_URI += "file://LICENSE-OASIS"
>
>  do_configure (){
>      :
> @@ -34,19 +58,19 @@ do_compile (){
>      :
>  }
>
> +inherit xmlcatalog
> +
>  do_install () {
>      install -d ${D}${sysconfdir}/xml/
>      xmlcatalog --create --noout ${D}${sysconfdir}/xml/docbook-xml.xml
>
> -    for DTDVERSION in 4.0 4.1.2 4.2 4.3 4.4 4.5; do
> +    for DTDVERSION in 4.1.2 4.2 4.3 4.4 4.5; do
>          DEST=${datadir}/xml/docbook/schema/dtd/$DTDVERSION
>          install -d -m 755 ${D}$DEST
> -        cp -v -R docbook-$DTDVERSION/* ${D}$DEST
> -        xmlcatalog --verbose --noout --add nextCatalog unused file://$DEST/catalog.xml ${D}${sysconfdir}/xml/docbook-xml.xml
> +        cp -v -R docbook-xml-$DTDVERSION/* ${D}$DEST
> +        xmlcatalog --verbose --noout --add nextCatalog unused \
> +          file://$DEST/catalog.xml ${D}${sysconfdir}/xml/docbook-xml.xml
>      done
>  }
>
> -XMLCATALOGS = "${sysconfdir}/xml/docbook-xml.xml"
> -inherit xmlcatalog
> -
>  FILES:${PN} = "${datadir}/* ${sysconfdir}/xml/docbook-xml.xml"
> --
> 2.34.1
>
>
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#177391): https://lists.openembedded.org/g/openembedded-core/message/177391
> Mute This Topic: https://lists.openembedded.org/mt/97074292/1686489
> Group Owner: openembedded-core+owner@lists.openembedded.org
> Unsubscribe: https://lists.openembedded.org/g/openembedded-core/unsub [alex.kanavin@gmail.com]
> -=-=-=-=-=-=-=-=-=-=-=-
>

Hi Richard,

Thanks for the patch!

There are a few things that need tweaking. Firstly, the shortlog and
commit log aren't quite right. The shortlog needs to be along the lines
of:

<area/recipename>: <short summary of the change>

so something like:

docbook-xml: Switch from debian packages to upstream docbook sources

This means someone glancing at the shortlogs can know which area it
applies to and what it was about (in summary).

After this you'd have a more verbose log message and I usually put the
[YOCTO #13270] at the end on a line of it's own.

I've commented a little more below inline. 

I think 4.0 support was removed, if so, that should be mentioned in the
commit message log. I then noticed the note about that is in the other
commit, it should be in this one!

On Sun, 2023-02-19 at 21:38 +0000, Richard Elberger wrote:
> ---
>  .../docbook-xml/docbook-xml-dtd4_4.5.bb       | 74 ++++++++++++-------
>  1 file changed, 49 insertions(+), 25 deletions(-)
> 
> diff --git a/meta/recipes-devtools/docbook-xml/docbook-xml-dtd4_4.5.bb b/meta/recipes-devtools/docbook-xml/docbook-xml-dtd4_4.5.bb
> index 2bec1442af..71aa8c14ec 100644
> --- a/meta/recipes-devtools/docbook-xml/docbook-xml-dtd4_4.5.bb
> +++ b/meta/recipes-devtools/docbook-xml/docbook-xml-dtd4_4.5.bb
> @@ -1,30 +1,54 @@
>  SUMMARY = "Document type definitions for verification of XML data files"
>  DESCRIPTION = "Document type definitions for verification of XML data \
> -files against the DocBook rule set, it ships with the latest DocBook 4.5 \
> -XML DTD, as well as a selected set of legacy DTDs for use with older \
> -documents, including 4.0, 4.1.2, 4.2, 4.3 and 4.4"
> -HOMEPAGE = "http://www.docbook.org/xml/"
> +files against the DocBook rule set."
> +HOMEPAGE = "https://docbook.org"
>  
> -LICENSE = "OASIS"
> -LIC_FILES_CHKSUM = "file://${WORKDIR}/LICENSE-OASIS;md5=c608985dd5f7f215e669e7639a0b1d2e"
> +inherit allarch
> +BBCLASSEXTEND = "native"

BBCLASSEXTEND by concention is at the end of the recipe. I see it moves
in the second patch and it wasn't clear what the two different purposes
of the patch were. Style fixes are ok as patch but if the first patch
is introducing them, we may as well squash things?
> 
> -# Note: the upstream sources are not distributed with a license file.
> -# LICENSE-OASIS is included as a "patch" to workaround this. When
> -# upgrading this recipe, please verify whether this is still needed.
> -SRC_URI = "http://snapshot.debian.org/archive/debian/20160728T043443Z/pool/main/d/docbook-xml/docbook-xml_${PV}.orig.tar.gz \
> -           file://LICENSE-OASIS \
> -           file://docbook-xml-update-catalog.xml.patch \
> -"
> +# To support apps with xml schema backward compatibility, we must
> +# install a set of schemas. Install the latest based on PV and then
> +# name any specific versions as required. TODO: Figure out a mechanism
> +# to filter exactly which versions are necessary, if that's even
> +# possible.
> +#
> +# DocBook.org lists available packages at https://docbook.org/xml/
> +#
> +# These packages are available as source but it requires the ability
> +# to use the Gradle build system to do so. It might be safer to use
> +# the source tree which would also enable proper SBOM generation
> +# through the bitbake build system. https://github.com/docbook/docbook

"packages" is an overloaded term. Do you mean packages here? Components
maybe?

> +# 
>  
> -SRC_URI[md5sum] = "487b4d44e15cffb1f4048af23f98208e"
> -SRC_URI[sha256sum] = "b0f8edcf697f5318e63dd98c9a931f3fee167af0805ba441db372e0f17b2a44f"
> +S = "${WORKDIR}"
>  
> -UPSTREAM_CHECK_URI = "${DEBIAN_MIRROR}/main/d/docbook-xml/"
> +SRC_URI += "https://docbook.org/xml/4.1.2/docbkx412.zip;name=payload412;subdir=docbook-xml-4.1.2"
> +SRC_URI[payload412.md5sum] = "900d7609fb7e6d78901b357e4acfbc17"

We've effectively dropped md5sums so there is no need to add new ones.

Cheers,

Richard

Thank you for the additional tips. This morning I was trying to close 
out the asks from yesterday. I was about to submit yet again and then I 
saw your message :D. I will need to try to get to the additional asks 
this evening instead given the workday is about to begin full on.

On 2/20/23 08:09, Richard Purdie wrote:
> Hi Richard,
>
> Thanks for the patch!
>
> There are a few things that need tweaking. Firstly, the shortlog and
> commit log aren't quite right. The shortlog needs to be along the lines
> of:
>
> <area/recipename>: <short summary of the change>
>
> so something like:
>
> docbook-xml: Switch from debian packages to upstream docbook sources
>
> This means someone glancing at the shortlogs can know which area it
> applies to and what it was about (in summary).
>
> After this you'd have a more verbose log message and I usually put the
> [YOCTO #13270] at the end on a line of it's own.
>
> I've commented a little more below inline.
>
> I think 4.0 support was removed, if so, that should be mentioned in the
> commit message log. I then noticed the note about that is in the other
> commit, it should be in this one!
>
> On Sun, 2023-02-19 at 21:38 +0000, Richard Elberger wrote:
>> ---
>>   .../docbook-xml/docbook-xml-dtd4_4.5.bb       | 74 ++++++++++++-------
>>   1 file changed, 49 insertions(+), 25 deletions(-)
>>
>> diff --git a/meta/recipes-devtools/docbook-xml/docbook-xml-dtd4_4.5.bb b/meta/recipes-devtools/docbook-xml/docbook-xml-dtd4_4.5.bb
>> index 2bec1442af..71aa8c14ec 100644
>> --- a/meta/recipes-devtools/docbook-xml/docbook-xml-dtd4_4.5.bb
>> +++ b/meta/recipes-devtools/docbook-xml/docbook-xml-dtd4_4.5.bb
>> @@ -1,30 +1,54 @@
>>   SUMMARY = "Document type definitions for verification of XML data files"
>>   DESCRIPTION = "Document type definitions for verification of XML data \
>> -files against the DocBook rule set, it ships with the latest DocBook 4.5 \
>> -XML DTD, as well as a selected set of legacy DTDs for use with older \
>> -documents, including 4.0, 4.1.2, 4.2, 4.3 and 4.4"
>> -HOMEPAGE = "http://www.docbook.org/xml/"
>> +files against the DocBook rule set."
>> +HOMEPAGE = "https://docbook.org"
>>   
>> -LICENSE = "OASIS"
>> -LIC_FILES_CHKSUM = "file://${WORKDIR}/LICENSE-OASIS;md5=c608985dd5f7f215e669e7639a0b1d2e"
>> +inherit allarch
>> +BBCLASSEXTEND = "native"
> BBCLASSEXTEND by concention is at the end of the recipe. I see it moves
> in the second patch and it wasn't clear what the two different purposes
> of the patch were. Style fixes are ok as patch but if the first patch
> is introducing them, we may as well squash things?
>> -# Note: the upstream sources are not distributed with a license file.
>> -# LICENSE-OASIS is included as a "patch" to workaround this. When
>> -# upgrading this recipe, please verify whether this is still needed.
>> -SRC_URI = "http://snapshot.debian.org/archive/debian/20160728T043443Z/pool/main/d/docbook-xml/docbook-xml_${PV}.orig.tar.gz \
>> -           file://LICENSE-OASIS \
>> -           file://docbook-xml-update-catalog.xml.patch \
>> -"
>> +# To support apps with xml schema backward compatibility, we must
>> +# install a set of schemas. Install the latest based on PV and then
>> +# name any specific versions as required. TODO: Figure out a mechanism
>> +# to filter exactly which versions are necessary, if that's even
>> +# possible.
>> +#
>> +# DocBook.org lists available packages at https://docbook.org/xml/
>> +#
>> +# These packages are available as source but it requires the ability
>> +# to use the Gradle build system to do so. It might be safer to use
>> +# the source tree which would also enable proper SBOM generation
>> +# through the bitbake build system. https://github.com/docbook/docbook
> "packages" is an overloaded term. Do you mean packages here? Components
> maybe?
>
>> +#
>>   
>> -SRC_URI[md5sum] = "487b4d44e15cffb1f4048af23f98208e"
>> -SRC_URI[sha256sum] = "b0f8edcf697f5318e63dd98c9a931f3fee167af0805ba441db372e0f17b2a44f"
>> +S = "${WORKDIR}"
>>   
>> -UPSTREAM_CHECK_URI = "${DEBIAN_MIRROR}/main/d/docbook-xml/"
>> +SRC_URI += "https://docbook.org/xml/4.1.2/docbkx412.zip;name=payload412;subdir=docbook-xml-4.1.2"
>> +SRC_URI[payload412.md5sum] = "900d7609fb7e6d78901b357e4acfbc17"
> We've effectively dropped md5sums so there is no need to add new ones.
>
> Cheers,
>
> Richard