From mboxrd@z Thu Jan 1 00:00:00 1970 X-GM-THRID: 6465956022541352960 X-Received: by 10.25.202.17 with SMTP id a17mr852838lfg.6.1505732703053; Mon, 18 Sep 2017 04:05:03 -0700 (PDT) X-BeenThere: isar-users@googlegroups.com Received: by 10.28.197.138 with SMTP id v132ls1499612wmf.25.gmail; Mon, 18 Sep 2017 04:05:02 -0700 (PDT) X-Google-Smtp-Source: ADKCNb6BfyzmU4+DBpk/jJ7sEPYsxDOyja9rXCIR9Tng12XpTJD9zVSACWNMrLpIZC3bmMwAV4Es X-Received: by 10.223.152.207 with SMTP id w73mr2000792wrb.13.1505732702592; Mon, 18 Sep 2017 04:05:02 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1505732702; cv=none; d=google.com; s=arc-20160816; b=s8DgG8ZsDJocu9rvDvkrE6Nqz+xvDVq4SYQKLoNeDuilk3LtUVlk/L6zNTP0YcOzOm 5uYm2n6o4KLSHEkAswW+v3njkWdRu11y1PKaw24+ZSOJYRp7sgigLvjQRDTZZtSry3kr HBuV7wNkgFquM5X9m2PMPCspDd55705A8COzf78wzUFes+VpD9i8rVisHYzeO/Ktq/ft aBtunzyTzrxNAdeQPBx/lGAaj8KRFzheyaib9CrxJ+ReUNzyFLgzQ5C1qJDwEUyW1hEJ HX/Snsv58Df0NsMdq7l39UfM2HMHdmtiYQOiCzOYArRJcMm0vsastUfSvfS7KD50vws5 dECA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:content-language:in-reply-to:mime-version :user-agent:date:message-id:from:references:cc:to:subject :arc-authentication-results; bh=yQM4jweA/ZldDCbvh82yTpHEpTn0Cmvpt4A/SVx0Q7s=; b=ltUGiEq/csvQmihEG3CyHMIrNvhJWQirNpdBDLddEuOVhYJkYty5+XLa7x4VbXGrZG WjzOs7vKBwAQwJveM0/lqnovNiGAUmMKKEbhnpSv9JleTxw78MbJynpT4PPlwhG6iMEZ zsCDElddAc0g4oyQx/i6HucJoXs2jzhbavZe6q5jjlPCa/NavBeKskpTCcHMZV7AQIVs esBfhoK016aLXpwOyWAdnY9f3IM9LiSlEoiiyn6w3Cup6pZR4OjZXWoWSqRUdKdKPBpl enqMDx4yzTLQMX97LUxGdc0aF0KHPpOozC+GCIfoV4TU8X0pFLIuYbx7vNZi/guHVVvp LVmA== ARC-Authentication-Results: i=1; gmr-mx.google.com; spf=pass (google.com: best guess record for domain of asmirnov@ilbers.de designates 85.214.62.211 as permitted sender) smtp.mailfrom=asmirnov@ilbers.de Return-Path: Received: from aqmola.ilbers.de (aqmola.ilbers.de. [85.214.62.211]) by gmr-mx.google.com with ESMTPS id 200si38159wmj.0.2017.09.18.04.05.02 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 18 Sep 2017 04:05:02 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of asmirnov@ilbers.de designates 85.214.62.211 as permitted sender) client-ip=85.214.62.211; Authentication-Results: gmr-mx.google.com; spf=pass (google.com: best guess record for domain of asmirnov@ilbers.de designates 85.214.62.211 as permitted sender) smtp.mailfrom=asmirnov@ilbers.de Received: from [10.0.2.15] ([188.227.110.165]) (authenticated bits=0) by aqmola.ilbers.de (8.14.4/8.14.4/Debian-4+deb7u1) with ESMTP id v8IB4xIm005791 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NOT); Mon, 18 Sep 2017 13:05:01 +0200 Subject: Re: [PATCH 3/4] doc: update user-manual.md To: Henning Schild Cc: isar-users@googlegroups.com References: <6458a21d-133e-e57e-0e88-7da19d8a9328@ilbers.de> <20170918124942.5bc276c0@md1em3qc> From: Alexander Smirnov Message-ID: <57a4d325-a5fe-a7e8-502f-a0d0fe031f5e@ilbers.de> Date: Mon, 18 Sep 2017 14:04:54 +0300 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.2.1 MIME-Version: 1.0 In-Reply-To: <20170918124942.5bc276c0@md1em3qc> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-TUID: SFat4iKpvrqh Hi, On 09/18/2017 01:49 PM, Henning Schild wrote: > Am Mon, 18 Sep 2017 11:33:38 +0300 > schrieb 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 >>> --- >>> 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 " >>> +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 ", 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. >