[PATCH v2 0/3] Update and expand system requirements

[PATCH v2 0/3] Update and expand system requirements

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Changes in V2

- Improve explanations in the various documents

- system-requirements: explicit the "core-image-sato" image was generated
  for the "qemux86-64" machine.

- Add minimum RAM requirements

Michael Opdenacker (3):
  manuals: update disk space requirements
  manuals: add rm_work disk space data
  manuals: add minimum RAM requirements

 documentation/brief-yoctoprojectqs/index.rst  |  8 +++++++-
 documentation/dev-manual/disk-space.rst       |  6 ++++++
 documentation/poky.yaml.in                    |  6 ++++++
 .../ref-manual/system-requirements.rst        | 19 +++++++++++++++++++
 4 files changed, 38 insertions(+), 1 deletion(-)

-- 
2.34.1

[PATCH v2 1/3] manuals: update disk space requirements

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Tests made on Poky master on March 16, 2023.

Add a "Free Disk Space" section to the "System Requirements" document.

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/brief-yoctoprojectqs/index.rst     |  4 +++-
 documentation/poky.yaml.in                       |  2 ++
 documentation/ref-manual/system-requirements.rst | 11 +++++++++++
 3 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
index 7b8baf233a..07e95ee85c 100644
--- a/documentation/brief-yoctoprojectqs/index.rst
+++ b/documentation/brief-yoctoprojectqs/index.rst
@@ -40,7 +40,9 @@ Compatible Linux Distribution
 Make sure your :term:`Build Host` meets the
 following requirements:
 
--  50 Gbytes of free disk space
+-  At least &MIN_DISK_SPACE; Gbytes of free disk space, though
+   much more will help to run multiple builds and increase
+   performance by reusing build artifacts.
 
 -  Runs a supported Linux distribution (i.e. recent releases of Fedora,
    openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux
diff --git a/documentation/poky.yaml.in b/documentation/poky.yaml.in
index 30e1050824..7810b8d2a5 100644
--- a/documentation/poky.yaml.in
+++ b/documentation/poky.yaml.in
@@ -41,3 +41,5 @@ MIN_TAR_VERSION : "1.28"
 MIN_GIT_VERSION : "1.8.3.1"
 MIN_GCC_VERSION : "7.5"
 MIN_MAKE_VERSION : "4.0"
+# Disk space (Gbytes) needed to generate qemux86-64 core-image-sato on Ubuntu 22.04 (x86-64), rounded up from 87
+MIN_DISK_SPACE : "90"
diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
index 0fbe3f12c8..bf50fc510a 100644
--- a/documentation/ref-manual/system-requirements.rst
+++ b/documentation/ref-manual/system-requirements.rst
@@ -31,6 +31,17 @@ and conceptual information in the :doc:`/overview-manual/index`.
 
 .. _detailed-supported-distros:
 
+Minimum Free Disk Space
+=======================
+
+To build an image such as ``core-image-sato`` for the ``qemux86-64`` machine,
+you need a system with at least &MIN_DISK_SPACE; Gbytes of free disk space.
+However, much more disk space will be necessary to build more complex images,
+to run multiple builds and to cache build artifacts, improving build efficiency.
+
+If you have a shortage of disk space, see the ":doc:`/dev-manual/disk-space`"
+section of the Development Tasks Manual.
+
 Supported Linux Distributions
 =============================
 
-- 
2.34.1

[PATCH v2 2/3] manuals: add rm_work disk space data

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/dev-manual/disk-space.rst | 6 ++++++
 documentation/poky.yaml.in              | 2 ++
 2 files changed, 8 insertions(+)

diff --git a/documentation/dev-manual/disk-space.rst b/documentation/dev-manual/disk-space.rst
index 3a5d2b7297..c63591cc7a 100644
--- a/documentation/dev-manual/disk-space.rst
+++ b/documentation/dev-manual/disk-space.rst
@@ -17,6 +17,12 @@ building a recipe once the recipe is built. For more information on
 "rm_work", see the :ref:`ref-classes-rm-work` class in the
 Yocto Project Reference Manual.
 
+When you inherit this class and build a ``core-image-sato`` image for a
+``qemux86-64`` machine from an Ubuntu 22.04 x86-64 system, you end up with a
+final disk usage of 22 Gbytes instead of &MIN_DISK_SPACE; Gbytes. However,
+&MIN_DISK_SPACE_RM_WORK; Gbytes of initial free disk space are still needed to
+create temporary files before they can be deleted.
+
 Purging Duplicate Shared State Cache Files
 ==========================================
 
diff --git a/documentation/poky.yaml.in b/documentation/poky.yaml.in
index 7810b8d2a5..eefdd3f30d 100644
--- a/documentation/poky.yaml.in
+++ b/documentation/poky.yaml.in
@@ -43,3 +43,5 @@ MIN_GCC_VERSION : "7.5"
 MIN_MAKE_VERSION : "4.0"
 # Disk space (Gbytes) needed to generate qemux86-64 core-image-sato on Ubuntu 22.04 (x86-64), rounded up from 87
 MIN_DISK_SPACE : "90"
+# Disk space (Gbytes) needed to generate qemux86-64 core-image-sato on Ubuntu 22.04 (x86-64) with "rm_work", rounded up from 38
+MIN_DISK_SPACE_RM_WORK : "40"
-- 
2.34.1

[PATCH v2 3/3] manuals: add minimum RAM requirements

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Measured by generating a "core-image-sato" image for a "qemux86-64"
machine from an Ubuntu 22.04 VM with 4 cores.

Less memory was not enough and caused Out of Memory failures.

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/brief-yoctoprojectqs/index.rst     | 4 ++++
 documentation/poky.yaml.in                       | 2 ++
 documentation/ref-manual/system-requirements.rst | 8 ++++++++
 3 files changed, 14 insertions(+)

diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
index 07e95ee85c..0ccffccc60 100644
--- a/documentation/brief-yoctoprojectqs/index.rst
+++ b/documentation/brief-yoctoprojectqs/index.rst
@@ -44,6 +44,10 @@ following requirements:
    much more will help to run multiple builds and increase
    performance by reusing build artifacts.
 
+-  At least &MIN_RAM; Gbytes of RAM, though a modern modern build host with as
+   much RAM and as many CPU cores as possible is strongly recommended to
+   maximize build performance.
+
 -  Runs a supported Linux distribution (i.e. recent releases of Fedora,
    openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux
    distributions that support the Yocto Project, see the
diff --git a/documentation/poky.yaml.in b/documentation/poky.yaml.in
index eefdd3f30d..dc0c257e50 100644
--- a/documentation/poky.yaml.in
+++ b/documentation/poky.yaml.in
@@ -45,3 +45,5 @@ MIN_MAKE_VERSION : "4.0"
 MIN_DISK_SPACE : "90"
 # Disk space (Gbytes) needed to generate qemux86-64 core-image-sato on Ubuntu 22.04 (x86-64) with "rm_work", rounded up from 38
 MIN_DISK_SPACE_RM_WORK : "40"
+# RAM (Gbytes) needed to generate qemux86-64 core-image-sato on Ubuntu 22.04 (x86-64) on a 4 core system
+MIN_RAM : "8"
diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
index bf50fc510a..4fe0cb841b 100644
--- a/documentation/ref-manual/system-requirements.rst
+++ b/documentation/ref-manual/system-requirements.rst
@@ -42,6 +42,14 @@ to run multiple builds and to cache build artifacts, improving build efficiency.
 If you have a shortage of disk space, see the ":doc:`/dev-manual/disk-space`"
 section of the Development Tasks Manual.
 
+Minimum System RAM
+==================
+
+You will manage to build an image such as ``core-image-sato`` for the
+``qemux86-64`` machine with as little as &MIN_RAM; Gbytes of RAM on an old
+system with 4 CPU cores, but your builds will be much faster on a system with
+as much RAM and as many CPU cores as possible.
+
 Supported Linux Distributions
 =============================
 
-- 
2.34.1