Merge branch 'feat/install_script_help' into 'master'

feat: Install script help

Closes IDFGH-9936 and IDF-6764

See merge request espressif/esp-idf!23506

install.bat

@@ -1,7 +1,7 @@
 @echo off
 if defined MSYSTEM (
 	echo This .bat file is for Windows CMD.EXE shell only.
-	goto end
+	goto :end
 )
 
 :: Missing requirements check
@@ -17,6 +17,11 @@ if not "%MISSING_REQUIREMENTS%" == "" goto :error_missing_requirements
 set IDF_PATH=%~dp0
 set IDF_PATH=%IDF_PATH:~0,-1%
 
+:: Print help if requested
+if /I "%1" == "/?" goto :help
+if /I "%1" == "-h" goto :help
+if /I "%1" == "--help" goto :help
+
 for /f "delims=" %%i in ('python.exe "%IDF_PATH%\tools\install_util.py" extract targets "%*"') do set TARGETS=%%i
 
 echo Installing ESP-IDF tools
@@ -44,4 +49,8 @@ goto :end
     echo For more details please visit our website: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/windows-setup.html
     goto :end
 
+:help
+    python.exe "%IDF_PATH%\tools\install_util.py" print_help bat
+    goto :end
+
 :end

install.fish

@@ -10,6 +10,14 @@ source "$IDF_PATH"/tools/detect_python.fish
 echo "Checking Python compatibility"
 "$ESP_PYTHON" "$IDF_PATH"/tools/python_version_checker.py
 
+for option in $argv
+    switch "$option"
+        case -h --help
+            "$ESP_PYTHON" "$IDF_PATH"/tools/install_util.py print_help fish
+            exit
+    end
+end
+
 set TARGETS ("$ESP_PYTHON" "$IDF_PATH"/tools/install_util.py extract targets $argv) || exit 1
 
 echo "Installing ESP-IDF tools"

install.ps1

@@ -1,6 +1,16 @@
 #!/usr/bin/env pwsh
+
+param(
+    [Switch]$h
+)
+
 $IDF_PATH = $PSScriptRoot
 
+if($h){
+python "$IDF_PATH/tools/install_util.py" print_help ps1
+Exit
+}
+
 $TARGETS = (python "$IDF_PATH/tools/install_util.py" extract targets "$args")
 
 Write-Output "Installing ESP-IDF tools"

install.sh

@@ -13,6 +13,14 @@ echo "Detecting the Python interpreter"
 echo "Checking Python compatibility"
 "${ESP_PYTHON}" "${IDF_PATH}/tools/python_version_checker.py"
 
+while getopts ":h" option; do
+    case $option in
+        h)
+            "${ESP_PYTHON}" "${IDF_PATH}/tools/install_util.py" print_help sh
+            exit;;
+    esac
+done
+
 TARGETS=`"${ESP_PYTHON}" "${IDF_PATH}/tools/install_util.py" extract targets "$@"`
 
 echo "Installing ESP-IDF tools"

tools/install_util.py

@@ -1,13 +1,16 @@
 #!/usr/bin/env python
 
-# SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
 #
 # SPDX-License-Identifier: Apache-2.0
 
 # This script is used from the $IDF_PATH/install.* scripts. This way the argument parsing can be done at one place and
 # doesn't have to be implemented for all shells.
 
 import argparse
+import json
+import os
+import sys
 from itertools import chain
 
 
@@ -47,6 +50,37 @@ def action_extract_targets(args: str) -> None:
     print(target_sep.join(targets or ['all']))
 
 
+def action_print_help(script_extension: str) -> None:
+    """
+    This function prints a help message explaining how to use the install scripts.
+    """
+
+    # extract the list of features from ./requirements.json
+    thisdir = os.path.dirname(os.path.realpath(__file__))
+    with open(f'{thisdir}/requirements.json', 'r') as f:
+        json_data = json.load(f)
+    features = [feat['name'] for feat in json_data['features']]
+
+    if script_extension == 'bat':
+        help_opts = '/?, -h, --help'
+    elif script_extension == 'ps1':
+        help_opts = '-h            '
+    else:
+        help_opts = '-h, --help    '
+
+    print(f"""usage: .{os.path.sep}install.{script_extension} [-h] [targets-to-install] [--enable-*] [--disable-*]
+
+optional arguments:
+  targets-to-install  'all', a single target (e.g. 'esp32s2'), or a comma-separated list of targets (e.g. 'esp32,esp32c3,esp32h2')
+  --enable-*          a specific feature to enable (e.g. '--enable-ttfw' will enable feature ttfw)
+  --disable-*         a specific feature to disable (e.g. '--disable-ttfw' will disable feature ttfw)
+                      supported features: {', '.join(features)}
+  {help_opts}      show this help message and exit
+
+For more information, please see https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tools/idf-tools.html#install-scripts
+  """)
+
+
 def main() -> None:
     parser = argparse.ArgumentParser()
 
@@ -56,9 +90,17 @@ def main() -> None:
     extract.add_argument('type', choices=['targets', 'features'])
     extract.add_argument('str-to-parse', nargs='?')
 
+    if 'print_help' in sys.argv:  # keep this option hidden until used
+        print_help = subparsers.add_parser('print_help', help='Show install script help')
+        print_help.add_argument('extension', choices=['sh', 'fish', 'ps1', 'bat'])
+
     args, unknown_args = parser.parse_known_args()
     # standalone "--enable-" won't be included into str-to-parse
 
+    if args.action == 'print_help':
+        action_print_help(args.extension)
+        sys.exit(0)
+
     action_func = globals()['action_{}_{}'.format(args.action, args.type)]
     str_to_parse = vars(args)['str-to-parse'] or ''
     action_func(' '.join(chain([str_to_parse], unknown_args)))