[1/2] ref-manual: add overlayfs-etc class

Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
---
 documentation/ref-manual/classes.rst | 41 ++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

Hi Slava,

Thanks for the documentation update patch!
See my comments below.

On 12/15/21 6:11 PM, Vyacheslav Yurkov wrote:
> Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
> ---
>  documentation/ref-manual/classes.rst | 41 ++++++++++++++++++++++++++++
>  1 file changed, 41 insertions(+)
>
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 2c191f407..a5b01c2cf 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -1769,6 +1769,47 @@ to the unit the following::
>  .. note::
>  
>     The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it.
> +   In order to get ``/etc`` in overlayfs see :ref:`overlayfs-etc <ref-classes-overlayfs-etc>` 
> +
> +.. _ref-classes-overlayfs-etc:
> +
> +``overlayfs-etc.bbclass``
> +=========================
> +
> +In order to have ``/etc`` directory in overlayfs a special handling at early 

s/to have/to have the/

> +boot stage is required.  The idea is to supply a custom init script that mounts
> +``/etc`` before launching actual init program, because the latter already


s/actual init program/the actual init program/

> +requires ``/etc`` to be mounted
> +
> +.. note::
> +
> +   This class must not be inherited directly. Use corresponding IMAGE_FEATURE
Oops, you forgot the "S" in "IMAGE_FEATURES". You may say:

Use :term:`IMAGE_FEATURES` or :term:`EXTRA_IMAGE_FEATURES`.

What about directly adding an example too?
> +
> +Your machine configuration should define at least device, mount point, and file system type
> +you are going to use for ``overlayfs``::


s/at least device/at least the device/

> +
> +  OVERLAYFS_ETC_MOUNT_POINT = "/data"
> +  OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
> +  OVERLAYFS_ETC_FSTYPE ?= "ext4"
> +
> +To control more mount options you should consider setting mount options
> +(``defaults`` is used by default)::
> +
> +  OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"
> +
> +The class provides two options for ``/sbin/init`` generation:
> +
> +* Default option is to rename original ``/sbin/init`` to ``/sbin/init.orig`` and

s/Default/The default/

s/original/the original/

> +  place generated init under original name, i.e. ``/sbin/init``. It has an advantage

s/generated init/the generated init/

s/original name/its original name/

> +  that you won't need to change any kernel parameters in order to make it work,
> +  but it poses a restriction that package-management can't be used, becaause updating


s/becaause/because/

> +  init manager would remove generated script


s/generated script/the generated script/

> +* If you are would like to keep original init as is, you can set::


s/If you are would like/If you wish/

> +
> +   OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0"
> +
> +  Then generated init will be named ``/sbin/preinit`` and you would need to extend your


/s/generated init/the generated init/

Cheers
Michael.

Hi Vyacheslav,

On December 15, 2021 6:11:37 PM GMT+01:00, Vyacheslav Yurkov <uvv.mail@gmail.com> wrote:
>Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
>---
> documentation/ref-manual/classes.rst | 41 ++++++++++++++++++++++++++++
> 1 file changed, 41 insertions(+)
>
>diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
>index 2c191f407..a5b01c2cf 100644
>--- a/documentation/ref-manual/classes.rst
>+++ b/documentation/ref-manual/classes.rst
>@@ -1769,6 +1769,47 @@ to the unit the following::
> .. note::
> 
>    The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it.
>+   In order to get ``/etc`` in overlayfs see :ref:`overlayfs-etc <ref-classes-overlayfs-etc>` 
>+

Missing dot at the end of the sentence.

>+.. _ref-classes-overlayfs-etc:
>+
>+``overlayfs-etc.bbclass``
>+=========================
>+
>+In order to have ``/etc`` directory in overlayfs a special handling at early 
>+boot stage is required.  The idea is to supply a custom init script that mounts
>+``/etc`` before launching actual init program, because the latter already
>+requires ``/etc`` to be mounted
>+

Missing dot at the end of the sentence.

>+.. note::
>+
>+   This class must not be inherited directly. Use corresponding IMAGE_FEATURE
>+

Missing dot at the end of the sentence.

>+Your machine configuration should define at least device, mount point, and file system type
>+you are going to use for ``overlayfs``::
>+
>+  OVERLAYFS_ETC_MOUNT_POINT = "/data"
>+  OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
>+  OVERLAYFS_ETC_FSTYPE ?= "ext4"
>+
>+To control more mount options you should consider setting mount options
>+(``defaults`` is used by default)::
>+
>+  OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"
>+
>+The class provides two options for ``/sbin/init`` generation:
>+
>+* Default option is to rename original ``/sbin/init`` to ``/sbin/init.orig`` and
>+  place generated init under original name, i.e. ``/sbin/init``. It has an advantage
>+  that you won't need to change any kernel parameters in order to make it work,
>+  but it poses a restriction that package-management can't be used, becaause updating
>+  init manager would remove generated script

What is the default value? This needs to be explicit otherwise it cannot be "undone" in a bbappends for example.

Thanks for the patch,
Cheers,
Quentin

>+* If you are would like to keep original init as is, you can set::
>+
>+   OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0"
>+
>+  Then generated init will be named ``/sbin/preinit`` and you would need to extend your
>+  kernel parameters manually in your bootloader configuration.
> 
> .. _ref-classes-own-mirrors:
>

Hi Quentin,
Thanks for the review

On 16.12.2021 18:37, Quentin Schulz wrote:
>
>> +
>> +  OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"
>> +
>> +The class provides two options for ``/sbin/init`` generation:
>> +
>> +* Default option is to rename original ``/sbin/init`` to ``/sbin/init.orig`` and
>> +  place generated init under original name, i.e. ``/sbin/init``. It has an advantage
>> +  that you won't need to change any kernel parameters in order to make it work,
>> +  but it poses a restriction that package-management can't be used, becaause updating
>> +  init manager would remove generated script
> What is the default value? This needs to be explicit otherwise it cannot be "undone" in a bbappends for example.
>
> Thanks for the patch,
> Cheers,
> Quentin

Could you please elaborate on default value of what we are talking here? 
For mandatory variables there are no default values, for two optional 
variables the default values are set with ??=.

Cheers,
Slava