From mboxrd@z Thu Jan 1 00:00:00 1970 X-GM-THRID: 6465956022541352960 X-Received: by 10.28.199.138 with SMTP id x132mr190852wmf.8.1505733621083; Mon, 18 Sep 2017 04:20:21 -0700 (PDT) X-BeenThere: isar-users@googlegroups.com Received: by 10.25.168.149 with SMTP id r143ls412340lfe.37.gmail; Mon, 18 Sep 2017 04:20:20 -0700 (PDT) X-Google-Smtp-Source: AOwi7QB0Jx9JWJqE5BbIQGItOO+VnZgXyChkiR6y+oJrxKh7pywv2j5wX/rrgaCkF+uRZLhBaQLc X-Received: by 10.46.21.77 with SMTP id 13mr2817480ljv.25.1505733620553; Mon, 18 Sep 2017 04:20:20 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1505733620; cv=none; d=google.com; s=arc-20160816; b=GkVE77A5Ovz7NA0X5VSLrVMpwvq2B5abY8V8R0u8exjEo9s6Efqlvuqx0RI+8EQMeP HNAsersKwntue73y8VSwr7kJn15Re04kcHTbppjWK4Q7pJrhI3XVGomqgLSB21iFZhoR K77nMsIBebO0+gNlCV1cnGTmrvjj4q/xLwHNdYKBGSWkIZHEjkKS9iq4ruNDaB0O971+ TmBtu+JB3uAGbgRR5rMZPTGmQtdhl2ZI9KhA6Lrew3tI3ZcHWYf6wKRSMt5xzABH2H9D BaCbpREyyWTgmgcKMYziR3dCfUXu3qjeKA5flnJ5fyPZyiR/M5bZ8wbu/2qlBe97Xrfv nocg== 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=NP2/jXOfdboeQSVf04yShoS9UX7LrVKk1JmPGVPP/YY=; b=XTVL52I0k6LKwtxW89FceXuiWQCIAaSpMVFaAalyBq71IPlpOxWttugSNwW1RNas0C GuhPp+PDIWupU0BkvM/+r4Kc9i/NFYweDx+tdpxQVZ6+Jay4ixDsw4gPMlaGQIuCuESr PQUeFjWFERw4sRcpbFbfbRXQBcntu55z3wBc79S5aamOFz7nAp1P2N3WERA0HRo2qxa8 oshliiZajcHtUocwqZAR5OO5XpzxLB61V3DSNwvSGEiNDBtW23yunY6tbghDGOn7tkMv /lA9ABpvs6RxD97iX/yObpiL+GFn4pP5ppT7KDAmuTrP2+xF+v7DLZKt7qHY2dSlr7pq yGug== 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 p200si524426wmg.4.2017.09.18.04.20.20 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 18 Sep 2017 04:20:20 -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 v8IBKHlS005840 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NOT); Mon, 18 Sep 2017 13:20:19 +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> <57a4d325-a5fe-a7e8-502f-a0d0fe031f5e@ilbers.de> <20170918130725.337ba68f@md1em3qc> From: Alexander Smirnov Message-ID: <6b2eb14f-d0a3-f557-1724-a2cd5f6dcd1e@ilbers.de> Date: Mon, 18 Sep 2017 14:20:12 +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: <20170918130725.337ba68f@md1em3qc> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-TUID: /nZ3mjl7ddo5 On 09/18/2017 02:07 PM, Henning Schild wrote: > Am Mon, 18 Sep 2017 14:04:54 +0300 > schrieb 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 : >>> >>>> 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. >> - `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