Re: [RFC PATCH v3 1/1] docs: ading dependencies documentation

[Andreas Reichel <andreas.reichel.ext@siemens.com>]

On Wed, Apr 03, 2019 at 11:13:04AM +0200, [ext] Silvano Cirujano Cuesta wrote:
> Signed-off-by: Silvano Cirujano Cuesta <silvano.cirujano-cuesta@siemens.com>
> ---
>  doc/dependencies.md | 255 ++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 255 insertions(+)
>  create mode 100644 doc/dependencies.md
> 
> diff --git a/doc/dependencies.md b/doc/dependencies.md
> new file mode 100644
> index 0000000..390e677
> --- /dev/null
> +++ b/doc/dependencies.md
> @@ -0,0 +1,255 @@
> +# Dependency management in ISAR
> +
> +## Introduction
> +
> +The typical goal of an ISAR build is to obtain:
> +
> +1. a disk image containing one or more partition images (all optional),
> +1. containing one or more Debian root filesystems with
> +1. certain Debian packages installed.
> 
(Should be 1., 2. and 3., so that one can easier read it as normal text
as well)

> +Reaching this goal relies on the availability of the above listed elements on *runtime*, the specification of the **[runtime environments](#runtime-environment-specification)** helps the different build tools ensuring the availability of the mentioned elements on runtime.
> +
> +Usually some of the runtime dependencies have to be built, and it happens in special environments. These **[buildtime environments](#buildtime-environment-specification)** help the different build tools preparing the environment for building the runtime dependencies.
> +
> +The differentiation between buildtime and runtime environments is very important.
> +The fact that ISAR uses Debian both for buildtime and runtime environments might mislead some people.
> +In general the names of the variables being used to specify those dependencies aren't supporting this differentiation, but difficulting it.
There is no 'difficulting'. => but making it difficult. / but
encumbering it.

(Is it a good idea to document, that ISAR makes it harder to people
instead of easier? :D)

> +
> +Not only the build environments have to be specified, but also the **[build process](#build-process-specification)** that takes care of building and integrating both the runtime dependencies and the buildtime dependencies.
> +
> +## Runtime environment specification
> +
> +As mentioned above, ISAR can build [partitioned disk images](#disk-image) or only [root filesystems](#root-filesystem).
> +
> +Let's first analyze how the content of the different runtime containers can be specified from bigger to smaller container.

... from bigger to smaller containerS
> +
> +


> +### Disk image
> +
> +A disk image depends on:
> +
> +1. a bootloader (optional) and
> +1. one or more partitions, containing one of them a [root filesystem](#root-filesystem).
> +

, one of them containing a [root filesystem]

> +
> +See following sections for more information about how to specify inter-tasks dependencies:

intertask dependencies
> +
> +
> +## Dependencies specification variables

## Variables for dependency specification

> +
> +### Bitbake `DEPENDS` variable
> +
> +This is a **Bitbake** variable that specifies **Bitbake inter-task dependencies**.
> +
intertask dependencies

> +Since it specifies the recipes that another recipe depend upon, this variable can be specified in **package recipes** and **image recipes**.
> +
> +### ISAR `IMAGE_INSTALL` variable
> +
> +This is originally a **Bitbake** variable that has conceptually the same goal in ISAR as in Yocto.

that conceptually has

> +In the case of ISAR it specifies at the same time **Bitbake inter-task dependencies** and **image custom Debian package dependencies**.
> +
In the case of ISAR it specifies **Bitbake intertask dependencies** and
**image custom Debian package dependencies** at the same time.


> +It basically specifies that a **[root filesystem](#root-filesystem)** (the prefix 'IMAGE' can be misleading here) requires a custom Debian package.
> +But since custom Debian packages are being built from package recipes, this variable also specifies that an image recipe depends on package recipes.
> +
> +For this "magic" to work both the Debian package and the package recipe have to have the same name.
                           ,

> +Something else than this 1:1 behaviour (e.g. a recipe creating multiple Debian binary packages out of a single Debian source package) requires some hacking out of the scope of this document.
> +
hacking, which is out of the scope of this document.

> +This variable can be found in **configuration files** and **image recipes**.
> +
> +### ISAR `IMAGE_PREINSTALL` variable
> +
> +This is an **ISAR-only** variable that specifies **image upstream Debian package dependencies**.
> +
> +It specifies that a **[root filesystem](#root-filesystem)** requires certain *upstream Debian packages*, being "upstream Debian packages" ready built packages that can be downloaded from a Debian package repository.
> +
being "upstream Debian packages" ready built packages.... .????????
I don't understand that :)

> +This is a variable that is rarely needed and only for a very specific use case!
> +That is when a package is needed in the **[root filesystem](#root-filesystem)** during the **root filesystem build stage**, but not in the final **[root filesystem](#root-filesystem)**.
> +Meaning that the installation is only transient, therefore its name.

As the name says, the installation is only transient.
> +
> +This variable can be found in **configuration files** and **image recipes**.
> +
> +### Debian `Depends` control-file value
> +
> +This is an **Debian** variable that specifies **Debian inter-package dependencies**.
> +
This is a

> +### Debian `Build-Depends` control-file value
> +
> +This is an **Debian** variable that specifies **Debian inter-package dependencies**.

This is a
> +
> +`Build-Depends` specifies the Debian packages that are required in the [buildtime environment](#buildtime-environment-specification) to build the package declaring the dependencies.
> +
> +It relies on standard Debian mechanisms, therefore the corresponding [official Debian documentation][pkg-rels] provides the best reference.
> +
> +### ISAR `IMAGER_BUILD_DEPS` variable
> +
> +This is an **ISAR-only** variable that specifies **Bitbake inter-task dependencies**.
> +
intertask

> +It has exactly the same effect as `DEPENDS`.
> +It simply provides syntactic sugar to separate dependencies on recipes for building the runtime environment from dependencies on recipes for building the **[imager](#imager)**.

It simply provides syntactic sugar to separate dependencies on recipes for building the runtime environment from those for building the **[imager](#imager)**.

> +
> +This variable can be found in **configuration files**.
> +
> +### ISAR `IMAGER_INSTALL` variable
> +
> +This is an **ISAR-only** variable that specifies **imager Debian package dependencies**.
> +
> +It specifies that certain *Debian packages* have to be installed on the **[imager](#imager)**.

installed FOR the

> +
> +This variable can be found typically in **configuration files**, although it could also be part of **image recipes**.
> +
can typically be found

can also be used in **image recipes**.

> +### ISAR `WIC_IMAGER_INSTALL` variable
> +
> +This is an **ISAR-only** variable that specifies **imager Debian package dependencies**.
> +
> +It specifies that an **[imager](#imager)** requires certain *Debian packages* so that WIC can build the disk images (e.g. `parted`).
> +
> +This variable can be found typically in **configuration files**, although it could also be part of **image recipes**.
> +
can typically be found in

can also be used in **image recipes**.

> +[wks]: https://www.yoctoproject.org/docs/current/ref-manual/ref-manual.html#ref-kickstart "OpenEmbedded Kickstart (.wks) Reference"
> +[pkg-rels]: https://www.debian.org/doc/debian-policy/ch-relationships.html "Debian policy: Declaring relationships between packages"
> -- 
> 2.11.0

KR
Andreas

> 
> -- 
> You received this message because you are subscribed to the Google Groups "isar-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to isar-users+unsubscribe@googlegroups.com.
> To post to this group, send email to isar-users@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/isar-users/20190403091304.8087-2-silvano.cirujano-cuesta%40siemens.com.
> For more options, visit https://groups.google.com/d/optout.

-- 
Andreas Reichel
Dipl.-Phys. (Univ.)
Software Consultant

Andreas.Reichel@tngtech.com, +49-174-3180074
TNG Technology Consulting GmbH, Betastr. 13a, 85774 Unterfoehring
Geschaeftsfuehrer: Henrik Klagges, Dr. Robert Dahlke, Gerhard Mueller
Sitz: Unterfoehring * Amtsgericht Muenchen * HRB 135082