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

[Alexander Smirnov <asmirnov@ilbers.de>]

On 09/18/2017 02:07 PM, Henning Schild wrote:
> Am Mon, 18 Sep 2017 14:04:54 +0300
> schrieb 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.
>>
  - `MAINTAINER` - The maintainer of the `deb` package we create

  + `MAINTAINER` - The maintainer of the `deb` package we create. If the 
maintainer is undefined, the recipe author should be mentioned here

Is it ok?

>>>    
>>>> 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:
> 
> Sure, will you fix that during merge or should i send a v2?

No problems, will do.

Alex

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

-- 
With best regards,
Alexander Smirnov

ilbers GmbH
Baierbrunner Str. 28c
D-81379 Munich
+49 (89) 122 67 24-0
http://ilbers.de/
Commercial register Munich, HRB 214197
General manager: Baurzhan Ismagulov