Re: [PATCH 4/5] doc: write something about "debianize"

[Jan Kiszka <jan.kiszka@siemens.com>]

On 29.10.19 17:44, Henning Schild wrote:
> From: Henning Schild <henning.schild@siemens.com>
> 
> Also add some comments to the implementation and extend the example
> recipe with some pre- and post-processing.
> 
> Signed-off-by: Henning Schild <henning.schild@siemens.com>
> ---
>  doc/user_manual.md                            | 19 ++++++++++++++++++-
>  .../recipes-app/samefile/samefile_2.14.bb     | 14 ++++++++++++++
>  meta/classes/debianize.bbclass                |  6 ++++++
>  3 files changed, 38 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/user_manual.md b/doc/user_manual.md
> index 34f50df..7c23fcc 100644
> --- a/doc/user_manual.md
> +++ b/doc/user_manual.md
> @@ -583,7 +583,7 @@ Isar currently supports two ways of creating custom packages.
>  
>  The `deb` packages are built using `dpkg-buildpackage`, so the sources should contain the `debian` directory with necessary meta information. This way is the default way of adding software that needs to be compiled from source. The bbclass for this approach is called `dpkg`.
>  
> -**NOTE:** If the sources do not contain a `debian` directory your recipe can fetch, create, or ship that.
> +**NOTE:** If the sources do not contain a `debian` directory your recipe can fetch, create, or ship that. You might want to read the the next section before returning here.
>  
>  This is also what you do if you want to rebuild/modify an upstream package.
>  Isar does understand `SRC_URI` entries starting with "apt://". For an example
> @@ -624,6 +624,23 @@ This approach prevents duplication of the license files in different packages.
>  
>  The last line in the example above adds recipe to the Isar work chain.
>  
> +### Compilation of sources missing the debian/-directory
> +
> +The `debian` directory contains meta information on how to build a package from source. This is roughly speaking "configure", "compile", "install" all described in a Debian-specific way.
> +Isar expects your sources to contain the `debian` folder and the above steps need to be described in it, not in a task in a recipe.
> +
> +So once you have sources you always need to combine them with a `debian` folder before Isar can build a package for you.
> +You might be able to find a debianization for a component on the internet, i.e. Ubuntu does package an open source component while Debian does not. Your recipe could download the `debian` folder from Ubuntu and the sources from the open source project.
> +
> +You can write it yourself, which can be pretty easy but requires a bit of studying. <https://www.debian.org/doc/debian-policy/index.html>
> +
> +Isar does actually contain a helper that aims to "debianize" sources for your. If your package uses a build-system that Debian knows and follows the well known "configure", "compile", "install" scheme that debianization might just fit your needs without reading Debian manuals.
> +If it does not fully fit your needs, it probably gives you a good starting point for your manual tuning.
> +
> +The shell function `deb_debianize` creates a `debian` folder. But it will not overwrite files that already are in WORKDIR. So you can either just call it to fully generate the `debian` folder. Or you combine it with pre-existing parts.
> +
> +Have a look at meta-isar/recipes-app/samefile/samefile_2.14.bb and meta/classes/debianize.bbclass for an example and the implementation.
> +
>  ### Packages without source
>  
>  If your customization is not about compiling from source there is a second way of creating `deb` packages. That way can be used for cases like:
> diff --git a/meta-isar/recipes-app/samefile/samefile_2.14.bb b/meta-isar/recipes-app/samefile/samefile_2.14.bb
> index a24d574..0ace85a 100644
> --- a/meta-isar/recipes-app/samefile/samefile_2.14.bb
> +++ b/meta-isar/recipes-app/samefile/samefile_2.14.bb
> @@ -12,5 +12,19 @@ SRC_URI[md5sum] = "0b438249f3549f18b49cbb49b0473f70"
>  
>  do_prepare_build[cleandirs] += "${S}/debian"
>  do_prepare_build() {
> +    # you could also create parts of your debianization before
> +    # pre-exisiting files will not be recreated

Let's write sentences and separate them.

> +    # 42 is not actually valid ... this is just a stupid example
> +    echo 42 > "${WORKDIR}"/compat

Don't we have a better example than writing something invalid which only
needs to be reverted later on?

> +
> +    # this step creates everything dpkg-buildpackage needs, compat will not be
> +    # overwritten
>      deb_debianize
> +
> +    # now if you are not happy you can post-process the result
> +    # now let us "repair" the compat
> +    echo 9 > "${S}/debian/compat"

Better append something to the generated file, maybe change the package
category or so.

> +    # compat happens to be used by this step, so do that again
> +    # see debianize.bbclass
> +    deb_create_control
>  }
> diff --git a/meta/classes/debianize.bbclass b/meta/classes/debianize.bbclass
> index fb9c234..e1c79ab 100644
> --- a/meta/classes/debianize.bbclass
> +++ b/meta/classes/debianize.bbclass
> @@ -76,23 +76,29 @@ EOF
>  }
>  
>  deb_debianize() {
> +	# create the compat-file if there is no file with that name in WORKDIR
>  	if [ -f ${WORKDIR}/compat ]; then
>  		install -v -m 644 ${WORKDIR}/compat ${S}/debian/compat
>  	else
>  		deb_create_compat
>  	fi
> +	# create the control-file if there is no contro-file in WORKDIR

control file

>  	if [ -f ${WORKDIR}/control ]; then
>  		install -v -m 644 ${WORKDIR}/control ${S}/debian/control
>  	else
>  		deb_create_control
>  	fi
> +	# create rules if WORKDIR does not contain a rules-file
>  	if [ -f ${WORKDIR}/rules ]; then
>  		install -v -m 755 ${WORKDIR}/rules ${S}/debian/rules
>  	else
>  		deb_create_rules
>  	fi
> +	# prepend a changelog-entry unless an existing changelog file already
> +	# contains an entry with CHANGELOG_V
>  	deb_add_changelog
>  
> +	# copy all hooks from WORKDIR into debian/, hooks are not generated
>  	for t in pre post
>  	do
>  		for a in inst rm
> 

Jan

-- 
Siemens AG, Corporate Technology, CT RDA IOT SES-DE
Corporate Competence Center Embedded Linux