[PATCH 0/4] Update default config and docs

[PATCH 0/4] Update default config and docs

[Henning Schild]

After the introduction of dpkg-raw this series updates the documentation and
the default config, as requested during the reviews.

Henning Schild (4):
  meta-isar: add 'example-raw' to example config
  doc: add 'binfmt-support' to list of required build host packages
  doc: update user-manual.md
  doc: Update technical overview

 doc/technical_overview.md        | 44 ++++++++++++++++++++++-----------
 doc/user_manual.md               | 53 +++++++++++++++++++++++++++++++++-------
 meta-isar/conf/local.conf.sample |  2 +-
 3 files changed, 75 insertions(+), 24 deletions(-)

-- 
2.13.5

[PATCH 1/4] meta-isar: add 'example-raw' to example config

[Henning Schild]

The example config is used by CI, where we want to cover all features.
Adding the example will cause CI to test dpkg-raw as well.

Signed-off-by: Henning Schild <henning.schild@siemens.com>
---
 meta-isar/conf/local.conf.sample | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/meta-isar/conf/local.conf.sample b/meta-isar/conf/local.conf.sample
index f141c22..a456b1b 100644
--- a/meta-isar/conf/local.conf.sample
+++ b/meta-isar/conf/local.conf.sample
@@ -153,7 +153,7 @@ CONF_VERSION = "1"
 
 #
 # The default list of extra packages to be installed.
-IMAGE_INSTALL = "hello"
+IMAGE_INSTALL = "hello example-raw"
 
 #
 # Default parallel jobs for bitbake:
-- 
2.13.5

[PATCH 2/4] doc: add 'binfmt-support' to list of required build host packages

[Henning Schild]

binfmt-support is used to automatically execute foreign architecture
binaries in qemu-user-static. The debian package qemu-user-static just
suggests installing it, but does not depend on it. Isar however depends
on it.

Signed-off-by: Henning Schild <henning.schild@siemens.com>
---
 doc/user_manual.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/user_manual.md b/doc/user_manual.md
index 8cba9a7..4707a68 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -62,6 +62,7 @@ parted
 python3                     # wic
 qemu
 qemu-user-static
+binfmt-support
 sudo
 ```
 
-- 
2.13.5

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

[Henning Schild]

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() {
+....
+}
+```
+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
+ - `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.
-- 
2.13.5

[PATCH 4/4] doc: Update technical overview

[Henning Schild]

The introduction of 'dpkg-raw' opens new ways to create custom packages.
Cover that in the overview.

Signed-off-by: Henning Schild <henning.schild@siemens.com>
---
 doc/technical_overview.md | 44 ++++++++++++++++++++++++++++++--------------
 1 file changed, 30 insertions(+), 14 deletions(-)

diff --git a/doc/technical_overview.md b/doc/technical_overview.md
index e83cbd0..f8ed9ee 100644
--- a/doc/technical_overview.md
+++ b/doc/technical_overview.md
@@ -24,7 +24,7 @@ executing process. Recipes in Isar can be split in two categories:
    infrastructure, manages Debian tools execution for package building and
    installation, generation root file system images
 
- - User recipes: custom user applications, that should be builе from sources
+ - User recipes: custom user applications, that can be built from sources
 
 There are two types of dependencies in Isar:
 
@@ -155,26 +155,42 @@ here: `meta-isar/recipes-core/images/files`, and it implements `do_build` task.
 
 ## 3.4 Building Custom Packages
 
-Isar provides possibility to build Debian packages from sources. This features
-works with Debian-like source packages, i.e. the source code tree should
-contain debian folder. The build process is implemented in
-`meta/classes/dpkg.bbclass` and consists from the following steps:
+Isar provides the possibility to build Debian packages from sources. This
+features works with Debian-like source packages, i.e. the source code tree
+should contain debian folder. This build process is implemented in
+`meta/classes/dpkg.bbclass`.
 
-1. Task `do_fetch`: fetch source code from external link
+Another way of creating Debian packages is implemented in
+`meta/classes/dpkg-raw.bbclass`. This class can be used for customizations that
+are not based on source code that should become a package.
 
-2. Task `do_unpack`: unpack source code to `${WORKDIR}`
+Both consist of the following steps:
 
-3. Task `do_build`: mount folder with source code to buildchroot, switch
-   to buildchroot using chroot command and run `build.sh` script. The
-   `build.sh` script performs the following:
+1. Task `do_fetch`: fetch files from external links
 
-   1. Go to `/home/build/${PN}`
+2. Task `do_unpack`: unpack those files to `${WORKDIR}`
 
-   2. Get list of dependencies from debian/control and install them using apt.
+3. Task `do_populate_package` _only_ for `dpkg-raw`: copy all you want in your
+   debian package to `${D}`, install hooks in `${D}/DEBIAN`
 
-   3. Run dpkg-buildpackage
+4. Task `do_build`: mount folder with unpacked files to buildchroot, execute
+   the actual build function `dpkg_runbuild`, and finally umount again
 
-4. Task `do_install`: install successfully built packages
+   4.1. the `dpkg_runbuild` function of `dpkg.bbclass` runs `build.sh` in the
+        buildchroot. That performs the following:
+
+        1. Go to `/home/build/${PN}`
+
+        2. Get list of dependencies from debian/control and install them.
+
+        3. Run dpkg-buildpackage
+
+   4.2. the `dpkg_runbuild` function of `dpkg-raw.bbclass` basically runs
+        `dpkg-deb` to construct a Debian package from a folder of files,
+	without compiling anything
+
+
+5. Task `do_install`: install successfully built packages
    `${WORKDIR}/*.deb` to deploy directory `${DEPLOY_DIR_DEB}`
 
 ## 3.5 Populate Target Filesystem
-- 
2.13.5

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

[Alexander Smirnov]

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

Re: [PATCH 4/4] doc: Update technical overview

[Alexander Smirnov]

On 09/15/2017 01:51 PM, Henning Schild wrote:
> The introduction of 'dpkg-raw' opens new ways to create custom packages.
> Cover that in the overview.
> 
> Signed-off-by: Henning Schild <henning.schild@siemens.com>
> ---
>   doc/technical_overview.md | 44 ++++++++++++++++++++++++++++++--------------
>   1 file changed, 30 insertions(+), 14 deletions(-)
> 
> diff --git a/doc/technical_overview.md b/doc/technical_overview.md
> index e83cbd0..f8ed9ee 100644
> --- a/doc/technical_overview.md
> +++ b/doc/technical_overview.md
> @@ -24,7 +24,7 @@ executing process. Recipes in Isar can be split in two categories:
>      infrastructure, manages Debian tools execution for package building and
>      installation, generation root file system images
>   
> - - User recipes: custom user applications, that should be builе from sources
> + - User recipes: custom user applications, that can be built from sources
>   
>   There are two types of dependencies in Isar:
>   
> @@ -155,26 +155,42 @@ here: `meta-isar/recipes-core/images/files`, and it implements `do_build` task.
>   
>   ## 3.4 Building Custom Packages
>   
> -Isar provides possibility to build Debian packages from sources. This features
> -works with Debian-like source packages, i.e. the source code tree should
> -contain debian folder. The build process is implemented in
> -`meta/classes/dpkg.bbclass` and consists from the following steps:
> +Isar provides the possibility to build Debian packages from sources. This
> +features works with Debian-like source packages, i.e. the source code tree

features -> feature

> +should contain debian folder. This build process is implemented in
> +`meta/classes/dpkg.bbclass`.
>   
> -1. Task `do_fetch`: fetch source code from external link
> +Another way of creating Debian packages is implemented in
> +`meta/classes/dpkg-raw.bbclass`. This class can be used for customizations that
> +are not based on source code that should become a package.
>   
> -2. Task `do_unpack`: unpack source code to `${WORKDIR}`
> +Both consist of the following steps:
>   
> -3. Task `do_build`: mount folder with source code to buildchroot, switch
> -   to buildchroot using chroot command and run `build.sh` script. The
> -   `build.sh` script performs the following:
> +1. Task `do_fetch`: fetch files from external links
>   
> -   1. Go to `/home/build/${PN}`
> +2. Task `do_unpack`: unpack those files to `${WORKDIR}`
>   
> -   2. Get list of dependencies from debian/control and install them using apt.
> +3. Task `do_populate_package` _only_ for `dpkg-raw`: copy all you want in your
> +   debian package to `${D}`, install hooks in `${D}/DEBIAN`
>   
> -   3. Run dpkg-buildpackage
> +4. Task `do_build`: mount folder with unpacked files to buildchroot, execute
> +   the actual build function `dpkg_runbuild`, and finally umount again
>   
> -4. Task `do_install`: install successfully built packages
> +   4.1. the `dpkg_runbuild` function of `dpkg.bbclass` runs `build.sh` in the
> +        buildchroot. That performs the following:
> +
> +        1. Go to `/home/build/${PN}`
> +
> +        2. Get list of dependencies from debian/control and install them.

This line is terminated by full stop, while others aren't.

The rest is ok for me, can fix these issues during merge.

Alex

> +
> +        3. Run dpkg-buildpackage
> +
> +   4.2. the `dpkg_runbuild` function of `dpkg-raw.bbclass` basically runs
> +        `dpkg-deb` to construct a Debian package from a folder of files,
> +	without compiling anything
> +
> +
> +5. Task `do_install`: install successfully built packages
>      `${WORKDIR}/*.deb` to deploy directory `${DEPLOY_DIR_DEB}`
>   
>   ## 3.5 Populate Target Filesystem
> 

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

[Henning Schild]

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. 

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

[Alexander Smirnov]

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

Re: [PATCH 4/4] doc: Update technical overview

[Henning Schild]

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

> On 09/15/2017 01:51 PM, Henning Schild wrote:
> > The introduction of 'dpkg-raw' opens new ways to create custom
> > packages. Cover that in the overview.
> > 
> > Signed-off-by: Henning Schild <henning.schild@siemens.com>
> > ---
> >   doc/technical_overview.md | 44
> > ++++++++++++++++++++++++++++++-------------- 1 file changed, 30
> > insertions(+), 14 deletions(-)
> > 
> > diff --git a/doc/technical_overview.md b/doc/technical_overview.md
> > index e83cbd0..f8ed9ee 100644
> > --- a/doc/technical_overview.md
> > +++ b/doc/technical_overview.md
> > @@ -24,7 +24,7 @@ executing process. Recipes in Isar can be split
> > in two categories: infrastructure, manages Debian tools execution
> > for package building and installation, generation root file system
> > images 
> > - - User recipes: custom user applications, that should be builе
> > from sources
> > + - User recipes: custom user applications, that can be built from
> > sources 
> >   There are two types of dependencies in Isar:
> >   
> > @@ -155,26 +155,42 @@ here: `meta-isar/recipes-core/images/files`,
> > and it implements `do_build` task. 
> >   ## 3.4 Building Custom Packages
> >   
> > -Isar provides possibility to build Debian packages from sources.
> > This features -works with Debian-like source packages, i.e. the
> > source code tree should -contain debian folder. The build process
> > is implemented in -`meta/classes/dpkg.bbclass` and consists from
> > the following steps: +Isar provides the possibility to build Debian
> > packages from sources. This +features works with Debian-like source
> > packages, i.e. the source code tree  
> 
> features -> feature
> 
> > +should contain debian folder. This build process is implemented in
> > +`meta/classes/dpkg.bbclass`.
> >   
> > -1. Task `do_fetch`: fetch source code from external link
> > +Another way of creating Debian packages is implemented in
> > +`meta/classes/dpkg-raw.bbclass`. This class can be used for
> > customizations that +are not based on source code that should
> > become a package. 
> > -2. Task `do_unpack`: unpack source code to `${WORKDIR}`
> > +Both consist of the following steps:
> >   
> > -3. Task `do_build`: mount folder with source code to buildchroot,
> > switch
> > -   to buildchroot using chroot command and run `build.sh` script.
> > The
> > -   `build.sh` script performs the following:
> > +1. Task `do_fetch`: fetch files from external links
> >   
> > -   1. Go to `/home/build/${PN}`
> > +2. Task `do_unpack`: unpack those files to `${WORKDIR}`
> >   
> > -   2. Get list of dependencies from debian/control and install
> > them using apt. +3. Task `do_populate_package` _only_ for
> > `dpkg-raw`: copy all you want in your
> > +   debian package to `${D}`, install hooks in `${D}/DEBIAN`
> >   
> > -   3. Run dpkg-buildpackage
> > +4. Task `do_build`: mount folder with unpacked files to
> > buildchroot, execute
> > +   the actual build function `dpkg_runbuild`, and finally umount
> > again 
> > -4. Task `do_install`: install successfully built packages
> > +   4.1. the `dpkg_runbuild` function of `dpkg.bbclass` runs
> > `build.sh` in the
> > +        buildchroot. That performs the following:
> > +
> > +        1. Go to `/home/build/${PN}`
> > +
> > +        2. Get list of dependencies from debian/control and
> > install them.  
> 
> This line is terminated by full stop, while others aren't.
> 
> The rest is ok for me, can fix these issues during merge.

Ok, in that case i will not send an update of this one.

Henning

> Alex
> 
> > +
> > +        3. Run dpkg-buildpackage
> > +
> > +   4.2. the `dpkg_runbuild` function of `dpkg-raw.bbclass`
> > basically runs
> > +        `dpkg-deb` to construct a Debian package from a folder of
> > files,
> > +	without compiling anything
> > +
> > +
> > +5. Task `do_install`: install successfully built packages
> >      `${WORKDIR}/*.deb` to deploy directory `${DEPLOY_DIR_DEB}`
> >   
> >   ## 3.5 Populate Target Filesystem
> >   

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

[Henning Schild]

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

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

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

[Alexander Smirnov]

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

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

[Henning Schild]

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

Re: [PATCH 0/4] Update default config and docs

[Alexander Smirnov]

Applied, thanks.

On 09/15/2017 01:51 PM, Henning Schild wrote:
> After the introduction of dpkg-raw this series updates the documentation and
> the default config, as requested during the reviews.
> 
> Henning Schild (4):
>    meta-isar: add 'example-raw' to example config
>    doc: add 'binfmt-support' to list of required build host packages
>    doc: update user-manual.md
>    doc: Update technical overview
> 
>   doc/technical_overview.md        | 44 ++++++++++++++++++++++-----------
>   doc/user_manual.md               | 53 +++++++++++++++++++++++++++++++++-------
>   meta-isar/conf/local.conf.sample |  2 +-
>   3 files changed, 75 insertions(+), 24 deletions(-)
>