From 7b556951f9b2583a778e66721e1a40dc9bbde993 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?=
 <manuel.pegourie-gonnard@arm.com>
Date: Wed, 9 Oct 2024 11:18:43 +0200
Subject: [PATCH] all.sh: document new file structure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
---
 tests/scripts/all-core.sh    | 22 +++++++++++++++++++---
 tests/scripts/all-helpers.sh | 10 +++++++++-
 tests/scripts/all.sh         |  3 +++
 3 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/tests/scripts/all-core.sh b/tests/scripts/all-core.sh
index adf8f0323..0e0a4a2d9 100644
--- a/tests/scripts/all-core.sh
+++ b/tests/scripts/all-core.sh
@@ -3,8 +3,6 @@
 # Copyright The Mbed TLS Contributors
 # SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
 
-
-
 ################################################################
 #### Documentation
 ################################################################
@@ -14,6 +12,24 @@
 #
 # To run all tests possible or available on the platform.
 #
+# Files structure
+# ---------------
+#
+# The executable entry point for users and the CI is tests/scripts/all.sh.
+#
+# The actual content is in the following files:
+# - all-core.sh contains the core logic for running test components,
+#   processing command line options, reporting results, etc.
+# - all-helpers.sh contains helper functions used by more than 1 component.
+# - components-*.sh contain the definitions of the various components.
+#
+# The first two parts are shared between repos and branches;
+# the component files are repo&branch-specific.
+#
+# The files all-*.sh and components-*.sh should only define functions and not
+# run code when sourced; the only exception being that all-core.sh runs
+# 'shopt' because that is necessary for the rest of the file to parse.
+#
 # Notes for users
 # ---------------
 #
@@ -143,7 +159,7 @@ pre_check_environment () {
 pre_load_components () {
     # Include the components from components.sh
     test_script_dir="${0%/*}"
-    for file in "$test_script_dir"/components*.sh; do
+    for file in "$test_script_dir"/components-*.sh; do
         source $file
     done
 }
diff --git a/tests/scripts/all-helpers.sh b/tests/scripts/all-helpers.sh
index de7c078db..7318a4a3c 100644
--- a/tests/scripts/all-helpers.sh
+++ b/tests/scripts/all-helpers.sh
@@ -3,7 +3,15 @@
 # Copyright The Mbed TLS Contributors
 # SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
 
-# This file contains helpers for test components that are executed by all.sh
+# This file contains helpers for test components that are executed by all.sh.
+# See "Files structure" in all-core.sh for other files used by all.sh.
+#
+# This file is the right place for helpers:
+# - that are used by more than one component living in more than one file;
+# - or (inclusive) that we want to share accross repos or branches.
+#
+# Helpers that are used in a single component file that is
+# repo&branch-specific can be defined in the file where they are used.
 
 ################################################################
 #### Helpers for components using libtestdriver1
diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh
index 8134b3715..6708de102 100755
--- a/tests/scripts/all.sh
+++ b/tests/scripts/all.sh
@@ -5,6 +5,9 @@
 # Copyright The Mbed TLS Contributors
 # SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
 
+# This file is executable; it is the entry point for users and the CI.
+# See "Files structure" in all-core.sh for other files used.
+
 # The path is going to change when this is moved to the framework
 test_script_dir="${0%/*}"
 source "$test_script_dir"/all-core.sh