From mboxrd@z Thu Jan 1 00:00:00 1970 X-GM-THRID: 6465956022541352960 X-Received: by 10.25.18.223 with SMTP id 92mr855812lfs.11.1505732832309; Mon, 18 Sep 2017 04:07:12 -0700 (PDT) X-BeenThere: isar-users@googlegroups.com Received: by 10.46.16.8 with SMTP id j8ls810494lje.16.gmail; Mon, 18 Sep 2017 04:07:11 -0700 (PDT) X-Google-Smtp-Source: AOwi7QDOdzGq9dod0sqJWdoHmN58LMbPyhSdxa8MZad0L9AbPZuXd2fJxvOLr2pXAUsICUHpxNlF X-Received: by 10.46.32.39 with SMTP id g39mr2832667ljg.17.1505732831884; Mon, 18 Sep 2017 04:07:11 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1505732831; cv=none; d=google.com; s=arc-20160816; b=RLoHq1e4Te8J5zAYnfYP/s3G6PZORLp4cPowiLm/DgfqPFm/cQB6vTu0WbAr4GjxbV F+atw7HFpr4s0/TAuVwCNjCMD0GmL2vmO/57Drxnu9wtdqIVICtbcUDnAnCu0xT3DCAq +qD6AZICXAWFHJAjnSRPBKV8w7qC6bHsflpKaYbdtdyKqZNu+q0VEbhHzqEmWVxpToGh bqahuf4i+dKz0Dqw3mA2AfRZErojscd6LD+P8N9wW2V4uUHach1nC1W2hyvjotiyOcUR 59us8/lj6YBrC8S42JV7rb5/8yh+3ukaSNJpEd1OLrFq6TIgRJPWXM9AlVIuui3RaQek MTDw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:subject:cc:to:from:date:arc-authentication-results; bh=ECfqd0iZbP0anZdQdXRm853ttlMLapHEBD4xfFGPYJU=; b=dDxAM9P+03IM2lc4JS404C7+HOxr5xNE0RvQTLNLiEPvjo3XEvEpu/2Fx+OD78QdN8 W2OeaM7M4htx6LjsaiI19Cn1CQxcxcKXNQCWlTc9xxP6rMPEjy2h7OgpceSSZLDy3wfF 4BJltn5gCpcyDrMKY14LxuugHZSDvS8pliTNgYzj/GpxW7eUCcDboXNEa8+iTagNKsJ+ QtQc6GldANNV8yEzzac7p42AkopJaOhDzRCCoSJ1gcKHrjXz+jsENJWZYLrwKk6byk3i 3nyFbaZYyffZ+yiXRuHHfspT6OsLywj7QZYkpn+Yw7Ps32MPAVugXE+fIi3vHawRShN9 Yx/g== ARC-Authentication-Results: i=1; gmr-mx.google.com; spf=neutral (google.com: 192.35.17.2 is neither permitted nor denied by best guess record for domain of henning.schild@siemens.com) smtp.mailfrom=henning.schild@siemens.com Return-Path: Received: from thoth.sbs.de (thoth.sbs.de. [192.35.17.2]) by gmr-mx.google.com with ESMTPS id c142si31290wmh.3.2017.09.18.04.07.11 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 18 Sep 2017 04:07:11 -0700 (PDT) Received-SPF: neutral (google.com: 192.35.17.2 is neither permitted nor denied by best guess record for domain of henning.schild@siemens.com) client-ip=192.35.17.2; Authentication-Results: gmr-mx.google.com; spf=neutral (google.com: 192.35.17.2 is neither permitted nor denied by best guess record for domain of henning.schild@siemens.com) smtp.mailfrom=henning.schild@siemens.com Received: from mail1.siemens.de (mail1.siemens.de [139.23.33.14]) by thoth.sbs.de (8.15.2/8.15.2) with ESMTPS id v8IB7B0o018327 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 18 Sep 2017 13:07:11 +0200 Received: from md1em3qc ([139.25.68.40]) by mail1.siemens.de (8.15.2/8.15.2) with ESMTP id v8IB7BnM020623; Mon, 18 Sep 2017 13:07:11 +0200 Date: Mon, 18 Sep 2017 13:07:25 +0200 From: Henning Schild To: Alexander Smirnov Cc: Subject: Re: [PATCH 3/4] doc: update user-manual.md Message-ID: <20170918130725.337ba68f@md1em3qc> In-Reply-To: <57a4d325-a5fe-a7e8-502f-a0d0fe031f5e@ilbers.de> References: <6458a21d-133e-e57e-0e88-7da19d8a9328@ilbers.de> <20170918124942.5bc276c0@md1em3qc> <57a4d325-a5fe-a7e8-502f-a0d0fe031f5e@ilbers.de> X-Mailer: Claws Mail 3.13.2 (GTK+ 2.24.31; x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-TUID: cwE/aM30Bubf 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. > > > > >> 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. > >