Move build option explanations in how to build guide to scons help message

Resolves: COMPMID-5381

Change-Id: I556e2269ff6350f58509624a3d3d94cb0853cb8d
Signed-off-by: Michalis Spyrou <michalis.spyrou@arm.com>
Reviewed-on: https://review.mlplatform.org/c/ml/ComputeLibrary/+/7882
Comments-Addressed: Arm Jenkins <bsgcomp@arm.com>
Tested-by: Arm Jenkins <bsgcomp@arm.com>
Reviewed-by: Pablo Marquez Tello <pablo.tello@arm.com>
Benchmark: Arm Jenkins <bsgcomp@arm.com>

3 files changed, 23 insertions, 217 deletions

diff --git a/SConstruct b/SConstruct
index 53cdc3b904..d3836ce9f9 100644
--- a/SConstruct
+++ b/SConstruct
@@ -89,12 +89,12 @@ vars.AddVariables(
     BoolVariable("debug", "Debug", False),
     BoolVariable("asserts", "Enable asserts (this flag is forced to 1 for debug=1)", False),
     BoolVariable("logging", "Enable Logging", False),
-    EnumVariable("arch", "Target Architecture", "armv7a",
+    EnumVariable("arch", "Target Architecture. The x86_32 and x86_64 targets can only be used with neon=0 and opencl=1.", "armv7a",
                   allowed_values=("armv7a", "armv7a-hf", "arm64-v8a", "arm64-v8.2-a", "arm64-v8.2-a-sve", "arm64-v8.2-a-sve2", "x86_32", "x86_64",
                                   "armv8a", "armv8.2-a", "armv8.2-a-sve", "armv8.6-a", "armv8.6-a-sve", "armv8.6-a-sve2", "armv8r64", "x86")),
     EnumVariable("estate", "Execution State", "auto", allowed_values=("auto", "32", "64")),
-    EnumVariable("os", "Target OS", "linux", allowed_values=("linux", "android", "tizen", "macos", "bare_metal", "openbsd","windows")),
-    EnumVariable("build", "Build type", "cross_compile", allowed_values=("native", "cross_compile", "embed_only")),
+    EnumVariable("os", "Target OS. With bare metal selected, only Arm® Neon™ (not OpenCL) can be used, static libraries get built and Neon™'s multi-threading support is disabled.", "linux", allowed_values=("linux", "android", "tizen", "macos", "bare_metal", "openbsd","windows")),
+    EnumVariable("build", "Either build directly on your device (native) or cross compile from your desktop machine (cross-compile). In both cases make sure the compiler is available in your path.", "cross_compile", allowed_values=("native", "cross_compile", "embed_only")),
     BoolVariable("examples", "Build example programs", True),
     BoolVariable("gemm_tuner", "Build gemm_tuner programs", True),
     BoolVariable("Werror", "Enable/disable the -Werror compilation flag", True),
@@ -102,17 +102,29 @@ vars.AddVariables(
     BoolVariable("standalone", "Builds the tests as standalone executables, links statically with libgcc, libstdc++ and libarm_compute", False),
     BoolVariable("opencl", "Enable OpenCL support", True),
     BoolVariable("neon", "Enable Arm® Neon™ support", False),
-    BoolVariable("embed_kernels", "Embed OpenCL kernels and OpenGL ES compute shaders in library binary", True),
-    BoolVariable("compress_kernels", "Compress embedded OpenCL kernels in library binary. Note embed_kernels should be enabled", False),
-    BoolVariable("set_soname", "Set the library's soname and shlibversion (requires SCons 2.4 or above)", False),
-    BoolVariable("openmp", "Enable OpenMP backend", False),
+    BoolVariable("embed_kernels", "Enable if you want the OpenCL kernels to be built in the library's binaries instead of being read from separate '.cl' / '.cs' files. If embed_kernels is set to 0 then the application can set the path to the folder containing the OpenCL kernel files by calling CLKernelLibrary::init(). By default the path is set to './cl_kernels'.", True),
+    BoolVariable("compress_kernels", "Compress embedded OpenCL kernels in library binary using zlib. Useful for reducing the binary size. embed_kernels should be enabled", False),
+    BoolVariable("set_soname", "If enabled the library will contain a SONAME and SHLIBVERSION and some symlinks will automatically be created between the objects. (requires SCons 2.4 or above)", False),
+    BoolVariable("openmp", "Enable OpenMP backend. Only works when building with g++ and not clang++", False),
     BoolVariable("cppthreads", "Enable C++11 threads backend", True),
     PathVariable("build_dir", "Specify sub-folder for the build", ".", PathVariable.PathAccept),
     PathVariable("install_dir", "Specify sub-folder for the install", "", PathVariable.PathAccept),
     BoolVariable("exceptions", "Enable/disable C++ exception support", True),
     BoolVariable("high_priority", "Generate a library containing only the high priority operators", False),
     PathVariable("linker_script", "Use an external linker script", "", PathVariable.PathAccept),
-    PathVariable("external_tests_dir", "Add examples, benchmarks and tests to the tests suite", "", PathVariable.PathAccept),
+    PathVariable("external_tests_dir", """Add examples, benchmarks and tests to the tests suite from an external path. In order to use this option, the external tests directory must have the following structure: 
+    EXTERNAL_TESTS_DIR:
+    └── tests
+        ├── benchmark
+        │   ├── CL
+        │   ├── datasets
+        │   ├── fixtures
+        │   └── Neon
+        └── validation
+            ├── CL
+            ├── datasets
+            ├── fixtures
+            └── Neon\n""", "", PathVariable.PathAccept),
     BoolVariable("experimental_dynamic_fusion", "Build the experimental dynamic fusion files", False),
     BoolVariable("experimental_fixed_format_kernels", "Enable fixed format kernels for GEMM", False),
     ListVariable("custom_options", "Custom options that can be used to turn on/off features", "none", ["disable_mmla_fp"]),
diff --git a/docs/user_guide/how_to_build_and_run_examples.dox b/docs/user_guide/how_to_build_and_run_examples.dox
index b1e8513577..e48b2b74eb 100644
--- a/docs/user_guide/how_to_build_and_run_examples.dox
+++ b/docs/user_guide/how_to_build_and_run_examples.dox
@@ -30,213 +30,7 @@ namespace arm_compute
 @section S1_1_build_options Build options
 
 scons 2.3 or above is required to build the library.
-To see the build options available simply run ```scons -h```:
-
-        debug: Debug (yes|no)
-            default: False
-
-        asserts: Enable asserts (this flag is forced to 1 for debug=1) (yes|no)
-            default: False
-
-        logging: Logging (this flag is forced to 1 for debug=1) (yes|no)
-            default: False
-
-        arch: Target Architecture (armv7a|x86_32|x86_64|armv8a|armv8.2-a|armv8.2-a-sve|armv8.2-a-sve2|armv8.6-a|armv8.6-a-sve|armv8.6-a-sve2|armv8r64|x86)
-            default: armv7a
-
-        estate: Execution State (auto|32|64)
-            default: auto
-
-        os: Target OS (linux|android|macos|tizen|bare_metal)
-            default: linux
-
-        build: Build type (native|cross_compile|embed_only)
-            default: cross_compile
-
-        examples: Build example programs (yes|no)
-            default: True
-
-        gemm_tuner: Build gemm_tuner programs (yes|no)
-            default: True
-
-        Werror: Enable/disable the -Werror compilation flag (yes|no)
-            default: True
-
-        standalone: Builds the tests as standalone executables, links statically with libgcc, libstdc++ and libarm_compute (yes|no)
-            default: False
-
-        opencl: Enable OpenCL support (yes|no)
-            default: True
-
-        neon: Enable Arm® Neon™ support (yes|no)
-            default: False
-
-        embed_kernels: Embed OpenCL kernels in library binary (yes|no)
-            default: True
-
-        compress_kernels: Compress embedded OpenCL kernels in library binary. Note embed_kernels should be enabled as well (yes|no)
-            default: False
-
-        set_soname: Set the library's soname and shlibversion (requires SCons 2.4 or above) (yes|no)
-            default: False
-
-        openmp: Enable OpenMP backend (yes|no)
-            default: False
-
-        cppthreads: Enable C++11 threads backend (yes|no)
-            default: True
-
-        build_dir: Specify sub-folder for the build ( /path/to/build_dir )
-            default: .
-
-        install_dir: Specify sub-folder for the install ( /path/to/install_dir )
-            default:
-
-        exceptions: Enable/disable C++ exception support (yes|no)
-            default: True
-
-        linker_script: Use an external linker script ( /path/to/linker_script )
-            default:
-
-        custom_options: Custom options that can be used to turn on/off features
-            (all|none|comma-separated list of names)
-            allowed names: disable_mmla_fp
-            default: none
-
-        data_type_support: Enable a list of data types to support
-            (all|none|comma-separated list of names)
-            allowed names: qasymm8 qasymm8_signed qsymm16 fp16 fp32
-            default: all
-
-        toolchain_prefix: Override the toolchain prefix
-            default:
-
-        compiler_prefix: Override the compiler prefix
-            default:
-
-        extra_cxx_flags: Extra CXX flags to be appended to the build command
-            default:
-
-        extra_link_flags: Extra LD flags to be appended to the build command
-            default:
-
-        compiler_cache: Command to prefix to the C and C++ compiler (e.g ccache)
-            default:
-
-        specs_file: Specs file to use
-            default: rdimon.specs
-
-        benchmark_examples: Build benchmark examples programs (yes|no)
-            default: False
-
-        validate_examples: Build validate examples programs (yes|no)
-            default: False
-
-        reference_openmp: Build reference validation with openmp (yes|no)
-            default: True
-
-        validation_tests: Build validation test programs (yes|no)
-            default: False
-
-        benchmark_tests: Build benchmark test programs (yes|no)
-            default: False
-
-        test_filter: Pattern to specify the tests' filenames to be compiled
-            default: *.cpp
-
-        pmu: Enable PMU counters (yes|no)
-            default: False
-
-        mali: Enable Arm® Mali™ hardware counters (yes|no)
-            default: False
-
-        external_tests_dir: Add examples, benchmarks and tests to the tests suite from an external path ( /path/to/external_tests_dir )
-            default:
-
-        high_priority: Generate a library using only the high priority operators
-            default: False
-
-        data_layout_support: Enable a list of data layout to support
-            default: False
-
-@b debug / @b asserts:
- - With debug=1 asserts are enabled, and the library is built with symbols and no optimisations enabled.
- - With debug=0 and asserts=1: Optimisations are enabled and symbols are removed, however all the asserts are still present (This is about 20% slower than the release build)
- - With debug=0 and asserts=0: All optimisations are enable and no validation is performed, if the application misuses the library it is likely to result in a crash. (Only use this mode once you are sure your application is working as expected).
-
-@b arch: The x86_32 and x86_64 targets can only be used with neon=0 and opencl=1.
-
-@b os: Choose the operating system you are targeting: Linux, Android or bare metal.
-@note bare metal can only be used for Arm® Neon™ (not OpenCL), only static libraries get built and Neon™'s multi-threading support is disabled.
-
-@b build: you can either build directly on your device (native) or cross compile from your desktop machine (cross-compile). In both cases make sure the compiler is available in your path.
-
-@note If you want to natively compile for 32bit on a 64bit Arm device running a 64bit OS then you will have to use cross-compile too.
-
-There is also an 'embed_only' option which will generate all the .embed files for the OpenCL kernels. This might be useful if using a different build system to compile the library.
-
-In addition the option 'compress_kernels' will compress the embedded OpenCL kernel files using zlib and inject them in the library. This is useful for reducing the binary size. Note, this option is only available for Android when 'embed_kernels' is enabled.
-
-@b Werror: If you are compiling using the same toolchains as the ones used in this guide then there shouldn't be any warning and therefore you should be able to keep Werror=1. If with a different compiler version the library fails to build because of warnings interpreted as errors then, if you are sure the warnings are not important, you might want to try to build with Werror=0 (But please do report the issue on Github).
-
-@b opencl / @b neon: Choose which SIMD technology you want to target. (Neon™ for Arm® Cortex®-A CPUs or OpenCL for Arm® Mali™ GPUs)
-
-@b embed_kernels: For OpenCL only: set embed_kernels=1 if you want the OpenCL kernels to be built in the library's binaries instead of being read from separate ".cl" / ".cs" files. If embed_kernels is set to 0 then the application can set the path to the folder containing the OpenCL kernel files by calling CLKernelLibrary::init(). By default the path is set to "./cl_kernels".
-
-@b set_soname: Do you want to build the versioned version of the library ?
-
-If enabled the library will contain a SONAME and SHLIBVERSION and some symlinks will automatically be created between the objects.
-Example:
-  libarm_compute_core.so -> libarm_compute_core.so.1.0.0
-  libarm_compute_core.so.1 -> libarm_compute_core.so.1.0.0
-  libarm_compute_core.so.1.0.0
-
-@note This options is disabled by default as it requires SCons version 2.4 or above.
-
-@b extra_cxx_flags: Custom CXX flags which will be appended to the end of the build command.
-
-@b build_dir: Build the library in a subfolder of the "build" folder. (Allows to build several configurations in parallel).
-
-@b examples: Build or not the examples
-
-@b validation_tests: Enable the build of the validation suite.
-
-@b benchmark_tests: Enable the build of the benchmark tests
-
-@b pmu: Enable the PMU cycle counter to measure execution time in benchmark tests. (Your device needs to support it)
-
-@b mali: Enable the collection of Arm® Mali™ hardware counters to measure execution time in benchmark tests. (Your device needs to have a Arm® Mali™ driver that supports it)
-
-@b openmp: Build in the OpenMP scheduler for Neon™.
-
-@note Only works when building with g++ not clang++
-
-@b cppthreads: Build in the C++11 scheduler for Neon™.
-
-@sa Scheduler::set
-
-@b external_tests_dir: Add examples, benchmarks and tests to the tests suite from an external path ( /path/to/external_tests_dir )
-
-In order to use this option, the external tests directory must have the following structure:
-
-    EXTERNAL_TESTS_DIR:
-    └── tests
-        ├── benchmark
-        │   ├── CL
-        │   ├── datasets
-        │   ├── fixtures
-        │   └── Neon
-        └── validation
-            ├── CL
-            ├── datasets
-            ├── fixtures
-            └── Neon
-
-Then, build the library with `external_tests_dir=<PATH_TO_EXTERNAL_TESTS_DIR>`.
-
-@b high_priority: Generate a library using only the high priority operators
-
-@b data_layout_support: Enable a list of data layout to support
+To see the build options available simply run ```scons -h```
 
 @section S1_2_linux Building for Linux
 
diff --git a/tests/framework/SConscript b/tests/framework/SConscript
index 72208eacad..450ffd77b0 100644
--- a/tests/framework/SConscript
+++ b/tests/framework/SConscript
@@ -30,8 +30,8 @@ Import('vars')
 
 # vars is imported from arm_compute:
 variables = [
-    BoolVariable("pmu", "Enable PMU counters", False),
-    BoolVariable("mali", "Enable Arm® Mali™ hardware counters", False),
+    BoolVariable("pmu", "Enable the PMU cycle counter to measure execution time in benchmark tests. (Your device needs to support it)", False),
+    BoolVariable("mali", "Enable the collection of Arm® Mali™ hardware counters to measure execution time in benchmark tests. (Your device needs to have a Arm® Mali™ driver that supports it)", False),
 ]
 
 # We need a separate set of Variables for the Help message (Otherwise the global variables will get displayed twice)