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

[Alexander Smirnov <asmirnov@ilbers.de>]

Hi,

On 09/18/2017 01:49 PM, Henning Schild wrote:
> 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.

I do not mean, that strict policy should be defined now.
I'd like to propose to define the default value for MAINTAINER, for 
example - recipe's author. Otherwise we possibly will have lots of 
recipes in future with template "Your name here <you@domain.com>", what 
I guess is incorrect usage of this variable, and moreover this will not 
conflict with this manual.

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

So, probably it makes sense to explicitly mention, that these variables 
are used by "dpkg-raw" class only.

- For the variables please have a look at the previous example, the 
following new variables are used in this recipe:

+ For the variables please have a look at the previous example, the 
following new variables are required by `dpkg-raw` class:

Alex

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