Re: [PATCH 3/4] doc: update user-manual.md

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

Am Mon, 18 Sep 2017 11:33:38 +0300
schrieb Alexander Smirnov <asmirnov@ilbers.de>:

> On 09/15/2017 01:51 PM, Henning Schild wrote:
> > The introduction of 'dpkg-raw.bbclass' changed the way people can
> > customize their images. Cover the new way in the manual. Along the
> > way also fix a few mistakes and slightly change structure.
> > 
> > Signed-off-by: Henning Schild <henning.schild@siemens.com>
> > ---
> >   doc/user_manual.md | 52
> > +++++++++++++++++++++++++++++++++++++++++++--------- 1 file
> > changed, 43 insertions(+), 9 deletions(-)
> > 
> > diff --git a/doc/user_manual.md b/doc/user_manual.md
> > index 4707a68..e2837c4 100644
> > --- a/doc/user_manual.md
> > +++ b/doc/user_manual.md
> > @@ -254,9 +254,9 @@ Isar workflow consists of stages described
> > below. 
> >   This filesystem is used as a build environment to compile custom
> > packages. It is generated using `apt` binaries repository, selected
> > by the user in configuration file. Please refer to distro
> > configuration chapter for more information. -### Custom Package
> > Compilation +### Custom Package Generation 
> > -During this stage Isar processes custom packages selected by the
> > user and generates binary `*.deb` packages for the target. Please
> > refer to custom packages compilation section for more information.
> > +During this stage Isar processes custom packages selected by the
> > user and generates binary `*.deb` packages for the target. Please
> > refer to custom packages generation section for more information.
> > ### Generation of Basic Target Filesystem @@ -336,14 +336,14 @@
> > DISTRO = "distro-name" ---
> >   
> > -## Custom Package Compilation
> > +## Custom Package Generation
> >   
> > -Isar provides possibility to compile and install custom packages.
> > The current version supports only building `deb` packages using
> > `dpkg-buildpackage`, so the sources should contain the `debian`
> > directory with necessary meta information. To add new package to
> > image, it needs the following: +To add new package to an image, do
> > the following: 
> > - - Create package recipe and put it in your `isar` layer.
> > + - Create a package recipe and put it in your `isar` layer.
> >    - Append `IMAGE_INSTALL` variable by this recipe name. If this
> > package should be included for all the machines, put
> > `IMAGE_INSTALL` to `local.conf` file. If you want to include this
> > package for specific machine, put it to your machine configuration
> > file. -Please refer to `add custom application` section for more
> > information about writing recipes. +Please refer to `Add a Custom
> > Application` section for more information about writing recipes.
> > --- @@ -484,12 +484,18 @@ Isar contains two image type classes that
> > can be used as reference: 
> >   ## Add a Custom Application
> >   
> > -Before creating new recipe it's highly recommended to take a look
> > into the BitBake user manual mentioned in Terms and Definitions
> > section. +Before creating a new recipe it's highly recommended to
> > take a look into the BitBake user manual mentioned in Terms and
> > Definitions section. -Current Isar version supports building
> > packages in Debian format only. The package must contain the
> > `debian` directory with the necessary metadata. +Isar currently
> > supports two ways of creating custom packages. -A typical Isar
> > recipe looks like this: +### Compilation of debianized-sources 
> > +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. + +
> > +#### Example ```
> >   DESCRIPTION = "Sample application for ISAR"
> >   
> > @@ -523,3 +529,31 @@ This approach prevents duplication of the
> > license files in different packages.
> >    - `SRC_REV` - Source code revision to fetch. Please check the
> > BitBake user manual for supported download formats. 
> >   The last line in the example above adds recipe to the Isar work
> > chain. +
> > +### 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: +
> > + - packaging binaries/files that where built outside of Isar
> > + - customization of the rootfs with package-hooks
> > + - pulling in dependancies (meta-packages)
> > +
> > +The bbclass for this approach is called `dpkg-raw`.
> > +
> > +#### Example
> > +```
> > +DESCRIPTION = "Sample application for ISAR"
> > +MAINTAINER = "Your name here <you@domain.com>"
> > +DEBIAN_DEPENDS = "apt"
> > +
> > +inherit dpkg-raw
> > +
> > +do_populate_package() {
> > +....  
> 
> Probably replace '....' by a comment. In the class there is already
> the line:
> 
>          bbnote "Put your files for this package in ${D}"
> 
> Otherwise this example is incomplete and have no sense, because
> anyway you have to read dpkg-raw class.

Yes, will include that comment.

> > +}
> > +```
> > +For the variables please have a look at the previous example, the
> > following new variables are used in this recipe:
> > + - `MAINTAINER` - The maintainer of the `deb` package we create  
> 
>  From this context it's not clear, who is maintainer of the package: 
> author, committer? If I add my new package, what should be written in 
> this field?

I guess that could be more verbose.

> Also I've noticed that MAINTAINER variable is introduced in this
> example only, but previous example (### Compilation of
> debianized-sources) in the text doesn't have this field. Is there any
> reason of doing so?

Well a dpkg-based example has the maintainer in some file in the
"debian" folder. Here i just talk about the two "new" variables that
the other class does not have.

Henning

> Alex
> 
> > + - `DEBIAN_DEPENDS` - Debian packages that the package depends on
> > +
> > +Have a look at the `example-raw` recipe to get an idea how the
> > `dpkg-raw` class can be used to customize your image.