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

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

Am Mon, 18 Sep 2017 14:20:12 +0300
schrieb 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?

Yes.

Henning

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