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

[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.

> +}
> +```
> +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?

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?

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.
>