[PATCH] docs: update VOLATILE_{LOG|TMP}_DIR

[PATCH] docs: update VOLATILE_{LOG|TMP}_DIR

[Trevor Woerner]

A new mechanism was introduced to handle whether or not tmp and log are
tmpfs-based (i.e. in RAM) or persist as real directories in the root
filesystem. The variables VOLATILE_LOG_DIR and VOLATILE_TMP_DIR no longer
exist, and PERMS files are used instead.

oe-core: 8d1ae67b89c4 ("bitbake.conf: drop VOLATILE_TMP_DIR, use FILESYSTEM_PERMS_TABLES instead")
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
 .../migration-guides/release-notes-5.0.rst    |  2 ++
 documentation/ref-manual/features.rst         |  4 +--
 documentation/ref-manual/variables.rst        | 32 ++++---------------
 3 files changed, 10 insertions(+), 28 deletions(-)

diff --git a/documentation/migration-guides/release-notes-5.0.rst b/documentation/migration-guides/release-notes-5.0.rst
index 800ba20a27b5..191debd0174a 100644
--- a/documentation/migration-guides/release-notes-5.0.rst
+++ b/documentation/migration-guides/release-notes-5.0.rst
@@ -335,6 +335,8 @@ New Features / Enhancements in 5.0
    -  Add minimal VS Code configuration to avoid VS Code's indexer from choking
       on build directories.
 
+   - VOLATILE_LOG_DIR and VOLATILE_TMP_DIR were removed in favour of the
+     FILESYSTEM_PERMS_TABLES mechanism.
 
 Known Issues in 5.0
 ~~~~~~~~~~~~~~~~~~~
diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst
index 2ea946b31d36..97c05cc2839f 100644
--- a/documentation/ref-manual/features.rst
+++ b/documentation/ref-manual/features.rst
@@ -323,8 +323,8 @@ The image features available for all images are:
 
    .. note::
 
-      To make the ``/var/log`` directory on the target persistent, use the
-      :term:`VOLATILE_LOG_DIR` variable by setting it to "no".
+      To make the ``/var/log`` directory on the target persistent, remove
+     ``files/fs-perms-volatile-log.txt`` from :term:`FILESYSTEM_PERMS_TABLES`.
 
 -  *ptest-pkgs:* Installs ptest packages for all ptest-enabled recipes.
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 32c9e7407dbc..994ee23e2709 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -13,7 +13,6 @@ system and gives an overview of their function and contents.
 :term:`K <KARCH>` :term:`L <LABELS>` :term:`M <MACHINE>`
 :term:`N <NATIVELSBSTRING>` :term:`O <OBJCOPY>` :term:`P`
 :term:`R <RANLIB>` :term:`S` :term:`T`
-:term:`U <UBOOT_CONFIG>` :term:`V <VOLATILE_LOG_DIR>`
 :term:`W <WARN_QA>` :term:`X <XSERVER>`
 
 .. glossary::
@@ -2994,11 +2993,12 @@ system and gives an overview of their function and contents.
       and users across an entire work project. It is best to do this in the
       packages themselves but this is not always possible.
 
-      By default, the OpenEmbedded build system uses the ``fs-perms.txt``,
-      which is located in the ``meta/files`` folder in the :term:`Source Directory`.
-      If you create your own file
-      permissions setting table, you should place it in your layer or the
-      distro's layer.
+      By default, the OpenEmbedded build system uses
+      ``fs-perms.txt``, ``fs-perms-volatile-log.txt``, and
+      ``files/fs-perms-volatile-tmp.txt`` which are located in the
+      ``meta/files`` folder in the :term:`Source Directory`. If you create
+      your own file permissions setting table, you should place it in your
+      layer or the distro's layer.
 
       You define the :term:`FILESYSTEM_PERMS_TABLES` variable in the
       ``conf/local.conf`` file, which is found in the :term:`Build Directory`,
@@ -9983,26 +9983,6 @@ system and gives an overview of their function and contents.
 
          PACKAGE_INSTALL = "${INITRAMFS_SCRIPTS} ${VIRTUAL-RUNTIME_base-utils} base-passwd"
 
-   :term:`VOLATILE_LOG_DIR`
-      Specifies the persistence of the target's ``/var/log`` directory,
-      which is used to house postinstall target log files.
-
-      By default, :term:`VOLATILE_LOG_DIR` is set to "yes", which means the
-      file is not persistent. You can override this setting by setting the
-      variable to "no" to make the log directory persistent.
-
-   :term:`VOLATILE_TMP_DIR`
-      Specifies the persistence of the target's ``/tmp`` directory.
-
-      By default, :term:`VOLATILE_TMP_DIR` is set to "yes", in which case
-      ``/tmp`` links to a directory which resides in RAM in a ``tmpfs``
-      filesystem.
-
-      If instead, you want the ``/tmp`` directory to be persistent, set the
-      variable to "no" to make it a regular directory in the root filesystem.
-
-      This supports both sysvinit and systemd based systems.
-
    :term:`WARN_QA`
       Specifies the quality assurance checks whose failures are reported as
       warnings by the OpenEmbedded build system. You set this variable in
-- 
2.44.0.501.g19981daefd7c

Re: [docs] [PATCH] docs: update VOLATILE_{LOG|TMP}_DIR

[Jörg Sommer]

[-- Attachment #1: Type: text/plain, Size: 780 bytes --]

Trevor Woerner via lists.yoctoproject.org schrieb am Mi 04. Sep, 13:27 (GMT):
> diff --git a/documentation/migration-guides/release-notes-5.0.rst b/documentation/migration-guides/release-notes-5.0.rst
> index 800ba20a27b5..191debd0174a 100644
> --- a/documentation/migration-guides/release-notes-5.0.rst
> +++ b/documentation/migration-guides/release-notes-5.0.rst
> @@ -335,6 +335,8 @@ New Features / Enhancements in 5.0
>     -  Add minimal VS Code configuration to avoid VS Code's indexer from choking
>        on build directories.
>  
> +   - VOLATILE_LOG_DIR and VOLATILE_TMP_DIR were removed in favour of the
> +     FILESYSTEM_PERMS_TABLES mechanism.

Would it be possible to expand this a bit? Like “replace VOLATILE_TMP_DIR by
…”


Regards, Jörg

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5068 bytes --]

Re: [docs] [PATCH] docs: update VOLATILE_{LOG|TMP}_DIR

[Quentin Schulz]

Hi Trevor,

On 9/4/24 7:27 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> A new mechanism was introduced to handle whether or not tmp and log are
> tmpfs-based (i.e. in RAM) or persist as real directories in the root
> filesystem. The variables VOLATILE_LOG_DIR and VOLATILE_TMP_DIR no longer
> exist, and PERMS files are used instead.
> 
> oe-core: 8d1ae67b89c4 ("bitbake.conf: drop VOLATILE_TMP_DIR, use FILESYSTEM_PERMS_TABLES instead")
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> ---
>   .../migration-guides/release-notes-5.0.rst    |  2 ++
>   documentation/ref-manual/features.rst         |  4 +--
>   documentation/ref-manual/variables.rst        | 32 ++++---------------
>   3 files changed, 10 insertions(+), 28 deletions(-)
> 
> diff --git a/documentation/migration-guides/release-notes-5.0.rst b/documentation/migration-guides/release-notes-5.0.rst
> index 800ba20a27b5..191debd0174a 100644
> --- a/documentation/migration-guides/release-notes-5.0.rst
> +++ b/documentation/migration-guides/release-notes-5.0.rst
> @@ -335,6 +335,8 @@ New Features / Enhancements in 5.0
>      -  Add minimal VS Code configuration to avoid VS Code's indexer from choking
>         on build directories.
>   
> +   - VOLATILE_LOG_DIR and VOLATILE_TMP_DIR were removed in favour of the
> +     FILESYSTEM_PERMS_TABLES mechanism.
>   

Maybe we could add some :term: here so people don't have to look for the 
new variable to use in the docs and just have to click on the link?

>   Known Issues in 5.0
>   ~~~~~~~~~~~~~~~~~~~
> diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst
> index 2ea946b31d36..97c05cc2839f 100644
> --- a/documentation/ref-manual/features.rst
> +++ b/documentation/ref-manual/features.rst
> @@ -323,8 +323,8 @@ The image features available for all images are:
>   
>      .. note::
>   
> -      To make the ``/var/log`` directory on the target persistent, use the
> -      :term:`VOLATILE_LOG_DIR` variable by setting it to "no".
> +      To make the ``/var/log`` directory on the target persistent, remove
> +     ``files/fs-perms-volatile-log.txt`` from :term:`FILESYSTEM_PERMS_TABLES`.
>   
>   -  *ptest-pkgs:* Installs ptest packages for all ptest-enabled recipes.
>   
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 32c9e7407dbc..994ee23e2709 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -13,7 +13,6 @@ system and gives an overview of their function and contents.
>   :term:`K <KARCH>` :term:`L <LABELS>` :term:`M <MACHINE>`
>   :term:`N <NATIVELSBSTRING>` :term:`O <OBJCOPY>` :term:`P`
>   :term:`R <RANLIB>` :term:`S` :term:`T`
> -:term:`U <UBOOT_CONFIG>` :term:`V <VOLATILE_LOG_DIR>`

I don't think this is appropriate here.

Instead:

:term:`U <UBOOT_CONFIG>` :term:`V <VIRTUAL-RUNTIME>`

>   :term:`W <WARN_QA>` :term:`X <XSERVER>`
>   
>   .. glossary::
> @@ -2994,11 +2993,12 @@ system and gives an overview of their function and contents.
>         and users across an entire work project. It is best to do this in the
>         packages themselves but this is not always possible.
>   
> -      By default, the OpenEmbedded build system uses the ``fs-perms.txt``,
> -      which is located in the ``meta/files`` folder in the :term:`Source Directory`.
> -      If you create your own file
> -      permissions setting table, you should place it in your layer or the
> -      distro's layer.
> +      By default, the OpenEmbedded build system uses
> +      ``fs-perms.txt``, ``fs-perms-volatile-log.txt``, and
> +      ``files/fs-perms-volatile-tmp.txt`` which are located in the
> +      ``meta/files`` folder in the :term:`Source Directory`. If you create
> +      your own file permissions setting table, you should place it in your
> +      layer or the distro's layer.

Where in my layer? Is there any variable I need to set in order for this 
new file to be found by BitBake? etc.

Do we want to explain what the default means for the persistence of 
which directories? The same way it was done for 
VOLATILE_LOG_DIR/VOLATILE_TMP_DIR?

Cheers,
Quentin