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

[Henning Schild <henning.schild@siemens.com>]

On Fri, 1 Nov 2019 00:08:35 -0700
<chombourger@gmail.com> wrote:

> On Tuesday, October 29, 2019 at 5:44:28 PM UTC+1, Henning Schild
> wrote:
> >
> > From: Henning Schild <hennin...@siemens.com <javascript:>> 
> >
> > Also add some comments to the implementation and extend the example 
> > recipe with some pre- and post-processing. 
> >
> > Signed-off-by: Henning Schild <hennin...@siemens.com <javascript:>> 
> > --- 
> >  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 
> > +    # 42 is not actually valid ... this is just a stupid example 
> > +    echo 42 > "${WORKDIR}"/compat 
> > + 
> > +    # this step creates everything dpkg-buildpackage needs, compat
> > will not be 
> > +    # overwritten 
> >      deb_debianize 
> > + 
> >  
> 
> do we want to "read compat <${S}/compat" before we overwrite it just
> to make sure it is still 42? and bbfatal if it isn't?
> in other words is this recipe more of a test or of an example?
> (either way is fine by me)

It is an example that is abused for partial testing. Good testing would
make it a bad example, so i will not change it.
If we ever get a testing layer, thorough testing of debianization would
be something to potentially add there.

Henning

> 
> > +    # now if you are not happy you can post-process the result 
> > +    # now let us "repair" the compat 
> > +    echo 9 > "${S}/debian/compat" 
> > +    # 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 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 
> > -- 
> > 2.23.0 
> >
> >  
>