Merge branch 'break/drop_gdbgui' into 'master'

Tools: Drop official support for gdbgui

Closes IDF-4627

See merge request espressif/esp-idf!39326

Author: dobairoland

docs/en/api-guides/jtag-debugging/using-debugger.rst

@@ -232,7 +232,7 @@ It is also possible to execute the described debugging tools conveniently from `
 
 4.  ``idf.py gdbgui``
 
-    Starts `gdbgui <https://www.gdbgui.com>`_ debugger frontend enabling out-of-the-box debugging in a browser window. To enable this option, run the install script with the "--enable-gdbgui" argument, e.g., ``install.sh --enable-gdbgui``.
+    Starts `gdbgui <https://www.gdbgui.com>`_ debugger frontend, which enables out-of-the-box debugging in a browser window. To enable this option, follow the `installation instructions <https://www.gdbgui.com/installation/>`_ to set up the tool using the ``pipx`` method. For system dependencies, restrictions, and other limitations, please refer to the installation page and the `issue tracker <https://github.com/cs01/gdbgui/issues>`_.
 
 
     You can combine these debugging actions on a single command line, allowing for convenient setup of blocking and non-blocking actions in one step. ``idf.py`` implements a simple logic to move the background actions (such as openocd) to the beginning and the interactive ones (such as gdb, monitor) to the end of the action list.

docs/en/migration-guides/release-6.x/6.0/index.rst

@@ -7,3 +7,4 @@ Migration from 5.5 to 6.0
     :maxdepth: 1
 
     peripherals
+    tools

docs/en/migration-guides/release-6.x/6.0/tools.rst

@@ -0,0 +1,25 @@
+Tools
+=====
+
+:link_to_translation:`zh_CN:[中文]`
+
+GDBGUI installation
+-------------------
+
+The support for the ``--enable-gdbgui`` argument  has been removed from the install scripts and `gdbgui <https://www.gdbgui.com>`_ cannot be installed this way anymore. Please use the ``pipx`` method from the `gdbgui installation guide <https://www.gdbgui.com/installation/>`_ in order to set up this tool.
+
+Depending on your operating system and Python version, you may need to consult the `list of known issues <https://github.com/cs01/gdbgui/issues>`_.
+
+For example, `Python 3.13 is not supported <https://github.com/cs01/gdbgui/issues/494>`_ on any operating systems at the moment.
+
+The Windows operating system is not supported since gdbgui version 0.14. Because of the existence of other issues, you will need Python 3.10 with some specific versions of the dependencies. The last know working gdbgui and dependency versions can be installed with the following command:
+
+```bash
+pipx install "gdbgui==0.13.2.0" "pygdbmi<=0.9.0.2" "python-socketio<5" "jinja2<3.1" "itsdangerous<2.1"
+```
+
+On Linux or MacOS, you can use Python 3.11 or 3.12 and gdbgui version 0.15.2.0.
+
+Please be aware that these recommendations may change over time and for an up-to-date list of issues refer to `the official issue tracker <https://github.com/cs01/gdbgui/issues>`_.
+
+We recommend to use ``idf.py gdb`` instead of ``idf.py gdbgui``, or debug in Eclipse/Vscode if you encounter an issue with the installation.

docs/zh_CN/api-guides/jtag-debugging/using-debugger.rst

@@ -232,7 +232,7 @@
 
 4.  ``idf.py gdbgui``
 
-    启动 `gdbgui <https://www.gdbgui.com>`_，在浏览器中打开调试器的前端界面。请在运行安装脚本时添加 "--enable-gdbgui" 参数，即运行 ``install.sh --enable-gdbgui``，从而确保支持 ``gdbgui`` 选项。
+    启动 `gdbgui <https://www.gdbgui.com>`_，在浏览器中打开调试器的前端界面。要启用此选项，请参照 `安装说明 <https://www.gdbgui.com/installation/>`_，使用 ``pipx`` 方法设置该工具。关于系统依赖项、限制及其他注意事项，请参考安装页面和 `问题追踪 <https://github.com/cs01/gdbgui/issues>`_。
 
 
     上述这些命令也可以合并到一起使用，``idf.py`` 会自动将后台进程（比如 openocd）最先运行，交互式进程（比如 GDB，monitor）最后运行。

docs/zh_CN/migration-guides/release-6.x/6.0/index.rst

@@ -7,3 +7,4 @@
     :maxdepth: 1
 
     peripherals
+    tools

docs/zh_CN/migration-guides/release-6.x/6.0/tools.rst

@@ -0,0 +1 @@
+.. include:: ../../../../en/migration-guides/release-6.x/6.0/tools.rst

tools/idf_py_actions/debug_ext.py

@@ -7,12 +7,6 @@
             "optional": false,
             "requirement_path": "tools/requirements/requirements.core.txt"
         },
-        {
-            "name": "gdbgui",
-            "description": "Packages for supporting debugging from web browser",
-            "optional": true,
-            "requirement_path": "tools/requirements/requirements.gdbgui.txt"
-        },
         {
             "name": "pytest",
             "description": "Packages for CI with pytest",

tools/requirements.json

@@ -23,7 +23,7 @@
     sys.path.append('..')
     import idf_tools
 
-IDF_PATH = os.environ.get('IDF_PATH', '../..')
+IDF_PATH = os.path.abspath(os.environ.get('IDF_PATH', '../..'))
 TOOLS_DIR = os.environ.get('IDF_TOOLS_PATH') or os.path.expanduser(idf_tools.IDF_TOOLS_PATH_DEFAULT)
 PYTHON_DIR = os.path.join(TOOLS_DIR, 'python_env')
 PYTHON_DIR_BACKUP = tempfile.mkdtemp()
@@ -32,7 +32,7 @@
 # Python 3.8 and 3.9 has a different error message that does not include the "No package metadata was found for" part
 REQ_MISSING = r'Package was not found and is required by the application: (No package metadata was found for )?{}'
 REQ_CORE = '- {}'.format(os.path.join(IDF_PATH, 'tools', 'requirements', 'requirements.core.txt'))
-REQ_GDBGUI = '- {}'.format(os.path.join(IDF_PATH, 'tools', 'requirements', 'requirements.gdbgui.txt'))
+REQ_DOCS = '- {}'.format(os.path.join(IDF_PATH, 'tools', 'requirements', 'requirements.docs.txt'))
 CONSTR = 'Constraint file: {}'.format(os.path.join(TOOLS_DIR, 'espidf.constraints'))
 
 # Set default global paths for idf_tools. If some test needs to
@@ -191,29 +191,29 @@ def test_default_arguments(self):  # type: () -> None
         output = self.run_idf_tools(['install-python-env'])
         self.assertIn(CONSTR, output)
         self.assertIn(REQ_CORE, output)
-        self.assertNotIn(REQ_GDBGUI, output)
+        self.assertNotIn(REQ_DOCS, output)
 
         output = self.run_idf_tools(['check-python-dependencies'])
         self.assertIn(REQ_SATISFIED, output)
 
     def test_opt_argument(self):  # type: () -> None
-        output = self.run_idf_tools(['install-python-env', '--features', 'gdbgui'])
+        output = self.run_idf_tools(['install-python-env', '--features', 'docs'])
         self.assertIn(CONSTR, output)
         self.assertIn(REQ_CORE, output)
-        self.assertIn(REQ_GDBGUI, output)
+        self.assertIn(REQ_DOCS, output)
 
         output = self.run_idf_tools(['install-python-env'])
-        # The gdbgui should be installed as well because the feature is is stored in the JSON file
+        # The docs should be installed as well because the feature is is stored in the JSON file
         self.assertIn(CONSTR, output)
         self.assertIn(REQ_CORE, output)
-        self.assertIn(REQ_GDBGUI, output)
+        self.assertIn(REQ_DOCS, output)
 
         # Argument that begins with '-' can't stand alone to be parsed as value
-        output = self.run_idf_tools(['install-python-env', '--features=-gdbgui'])
-        # After removing the gdbgui should not be present
+        output = self.run_idf_tools(['install-python-env', '--features=-docs'])
+        # After removing the docs should not be present
         self.assertIn(CONSTR, output)
         self.assertIn(REQ_CORE, output)
-        self.assertNotIn(REQ_GDBGUI, output)
+        self.assertNotIn(REQ_DOCS, output)
 
     def test_no_constraints(self):  # type: () -> None
         output = self.run_idf_tools(['install-python-env', '--no-constraints'])