diff --git a/docs/en/additionalfeatures/clangd_cdt_support.rst b/docs/en/additionalfeatures/clangd_cdt_support.rst index 048813521..ace1c665e 100644 --- a/docs/en/additionalfeatures/clangd_cdt_support.rst +++ b/docs/en/additionalfeatures/clangd_cdt_support.rst @@ -3,17 +3,20 @@ Espressif-IDE LSP Support for C/C++ Editor ========================================== -The Espressif-IDE 3.0.0 (and higher) now includes the `Eclipse CDT-LSP `, enabling support for the latest C/C++ standards and providing an LSP-based C/C++ Editor. This editor, powered by the `LLVM ` clangd C/C++ language server, offers advanced functionality for ESP-IDF developers. +:link_to_translation:`zh_CN:[中文]` -In line with this enhancement, we've discontinued support for the standard CDT Editor/Indexer, as it only offers support for up to C++ 14. This has been replaced with a new LSP editor, especially considering that ESP-IDF now utilizes C++ 20 (with GCC 11.2) in v5.0.x, transitions to C++ 23 (with GCC 12.1) in v5.1, and to C++ 23 with GCC 13.1 in v5.2. +The Espressif-IDE 3.0.0 or later now includes the `Eclipse CDT-LSP `_, enabling support for the latest C/C++ standards and providing an LSP-based C/C++ Editor. This editor, powered by the `LLVM `_ clangd C/C++ language server, offers advanced functionality for ESP-IDF developers. + +In line with this enhancement, we have discontinued support for the standard CDT Editor/Indexer, as it only supports up to C++ 14. This has been replaced with a new LSP editor, especially considering that ESP-IDF now utilizes C++ 20 (with GCC 11.2) in v5.0.x, transitions to C++ 23 (with GCC 12.1) in v5.1, and to C++ 23 with GCC 13.1 in v5.2. The LSP powered C/C++ editor greatly benefits ESP-IDF developers by aligning with the latest language standards and compiler versions, enhancing productivity, and improving code quality. -You can find more details on the LSP based C/C++ Editor features in the `Eclipse CDT-LSP documentation `_. +You can find more details on the LSP based C/C++ editor features in the `Eclipse CDT-LSP documentation `_. Prerequisites ------------- -* You need to have Espressif-IDE 3.0.0 (and higher) to have access to the LSP powered C/C++ editor. + +* You need Espressif-IDE 3.0.0 or later to access the LSP-powered C/C++ editor. * If you are updating Eclipse CDT or Espressif-IDE via the update site, you need to select the ESP-IDF Eclipse Plugin and its dependencies, as shown below: .. image:: ../../../media/clangd/cdtlsp_updatesite.png @@ -21,34 +24,34 @@ Prerequisites Clangd Configuration -------------------- -By default, the esp-clang toolchain is installed as a part of the ESP-IDF tools installation process, and clangd **Path** is configured in the preferences. +By default, the esp-clang toolchain is installed as a part of the ESP-IDF tools installation process, and clangd ``Path`` is configured in the preferences. -The **Drivers** path and **--compile-commands-dir** path will be configured based on the selected target (esp32, esp32c6 etc.) and the project you're building. +The ``Drivers`` path and ``--compile-commands-dir`` path will be configured based on the selected target (esp32, esp32c6, etc.) and the project being built. However, if there are any issues in configuration, this can be configured in the following way: -1. Go to `Window` > `Preferences` > `C/C++` > `Editor(LSP)` -2. Navigate to `clangd` node -3. Provide `Drivers` path as shown in the screenshot. -4. Set `--compile-commands-dir=/project/build` in the additional argument section. -5. Click on `Apply and Close`. +1. Go to ``Window`` > ``Preferences`` > ``C/C++`` > ``Editor(LSP)``. +2. Navigate to ``clangd`` node. +3. Provide ``Drivers`` path as shown in the screenshot. +4. Set ``--compile-commands-dir=/project/build`` in the additional argument section. +5. Click on ``Apply and Close``. - .. image:: ../../../media/clangd/clangd_config.png + .. image:: ../../../media/clangd/clangd_config.png -By default, when you create a new project, a `.clangd` configuration file is created with the following arguments. +By default, when you create a new project, a ``.clangd`` configuration file is created with the following arguments. -However, if you are dealing with an existing project, please create a `.clangd` file at the root of the project and add the following content. +However, if you are dealing with an existing project, please create a ``.clangd`` file at the root of the project and add the following content. .. code-block:: yaml CompileFlags: - CompilationDatabase: build - Remove: [-m*, -f*] + CompilationDatabase: build + Remove: [-m*, -f*] -How to fix Unknown argument error when navigating to the esp-idf components ----------------------------------------------------------------------------------------- +How to Fix the "Unknown Argument" Error When Navigating to ESP-IDF Components +----------------------------------------------------------------------------- -If you are seeing the following error markers while navigating to the esp-idf components source code: +If you see the following error markers while navigating to the ESP-IDF component source code: .. code-block:: none @@ -59,34 +62,34 @@ If you are seeing the following error markers while navigating to the esp-idf co Please follow the steps below to fix it: -1. Download the script for `fix_compile_commands.py `_. +1. Download the script for `fix_compile_commands.py `_. -2. Invoke the script from the project post build step. Here is example for `CMakeLists.txt `_: +2. Invoke the script from the project post build step. Here is example for `CMakeLists.txt `_: - .. code-block:: cmake + .. code-block:: cmake - if(EXISTS "${CMAKE_SOURCE_DIR}/fix_compile_commands.py") - add_custom_target( - fix_clangd ALL - COMMAND ${CMAKE_COMMAND} -E echo "Running fix_compile_commands.py..." - COMMAND ${CMAKE_COMMAND} -E env python3 ${CMAKE_SOURCE_DIR}/fix_compile_commands.py - COMMENT "Cleaning compile_commands.json for clangd" - VERBATIM - ) - endif() + if(EXISTS "${CMAKE_SOURCE_DIR}/fix_compile_commands.py") + add_custom_target( + fix_clangd ALL + COMMAND ${CMAKE_COMMAND} -E echo "Running fix_compile_commands.py..." + COMMAND ${CMAKE_COMMAND} -E env python3 ${CMAKE_SOURCE_DIR}/fix_compile_commands.py + COMMENT "Cleaning compile_commands.json for clangd" + VERBATIM + ) + endif() -3. Now run the build, the script will remove the -m* and -f* flags from the compile_commands.json file which are unknown to clangd. +3. Run the build, the script will remove the ``-m*`` and ``-f*`` flags from the ``compile_commands.json`` file which are unknown to clangd. -4. Now, you can navigate to the esp-idf components source code without any errors. +4. Now, you can navigate to the ESP-IDF components source code without any errors. Disable CDT Indexer ------------------- -With Espressif-IDE 3.0.0 (and higher), the CDT Indexer is disabled by default; instead, the LSP Indexer server will be used for code analysis. +With Espressif-IDE 3.0.0 or later, the CDT Indexer is disabled by default; instead, the LSP Indexer server is used for code analysis. -If, for some reason, it is not disabled, please follow the steps below to disable it. +If, for any reason, it is not disabled, follow the steps below to disable it. -1. Go to `Window` > `Preferences` > `C/C++` > `Indexer` -2. Uncheck `Enable Indexer` option and then click on `Apply and Close`. +1. Go to ``Window`` > ``Preferences`` > ``C/C++`` > ``Indexer``. +2. Uncheck ``Enable Indexer`` option and then click on ``Apply and Close``. - .. image:: ../../../media/clangd/cdt_indexer_disable.png + .. image:: ../../../media/clangd/cdt_indexer_disable.png diff --git a/docs/zh_CN/additionalfeatures/clangd_cdt_support.rst b/docs/zh_CN/additionalfeatures/clangd_cdt_support.rst index 318ab6cc3..99777ae2f 100644 --- a/docs/zh_CN/additionalfeatures/clangd_cdt_support.rst +++ b/docs/zh_CN/additionalfeatures/clangd_cdt_support.rst @@ -1 +1,95 @@ -.. include:: ../../en/additionalfeatures/clangd_cdt_support.rst +.. _clangd_cdt_support: + +Espressif-IDE 对 C/C++ 编辑器的 LSP 支持 +======================================== + +:link_to_translation:`en:[English]` + +Espressif-IDE 3.0.0 及更高版本现已内置 `Eclipse CDT-LSP `_，支持最新的 C/C++ 标准并提供基于 LSP 的 C/C++ 编辑器。该编辑器由 `LLVM `_ clangd C/C++ 语言服务器驱动，为 ESP-IDF 开发者提供更强大的功能。 + +为配合本次功能增强，我们已停止支持标准的 CDT 编辑器/索引器，因为其仅支持至 C++ 14。我们用全新的 LSP 编辑器取而代之，尤其考虑到 ESP-IDF 现已在 v5.0.x 中使用 C++ 20（配合 GCC 11.2），在 v5.1 过渡到 C++ 23（配合 GCC 12.1），并在 v5.2 使用 GCC 13.1 的 C++ 23。 + +基于 LSP 的 C/C++ 编辑器与最新的语言标准和编译器版本保持一致，可极大提升 ESP-IDF 开发者的效率并改进代码质量。 + +关于基于 LSP 的 C/C++ 编辑器功能的更多信息，请参阅 `Eclipse CDT-LSP 文档 `_。 + +准备工作 +-------- + +* 需要 Espressif-IDE 3.0.0 及更高版本才能使用基于 LSP 的 C/C++ 编辑器。 +* 如果通过更新站点升级 Eclipse CDT 或 Espressif-IDE，需要选择 ESP-IDF Eclipse 插件及其依赖项，如下图所示。 + + .. image:: ../../../media/clangd/cdtlsp_updatesite.png + +Clangd 配置 +----------- + +默认情况下，esp-clang 工具链会在 ESP-IDF 工具的安装过程中自动安装，并且会在偏好设置中配置好 clangd 的 ``Path``。 + +``Drivers`` 路径和 ``--compile-commands-dir`` 路径会根据所选目标（esp32、esp32c6 等）以及当前正在构建的项目自动配置。 + +如果自动配置有问题，可按以下方式手动配置： + +1. 前往 ``Window`` > ``Preferences`` > ``C/C++`` > ``Editor(LSP)``。 +2. 定位到 ``clangd`` 节点。 +3. 按截图所示填写 ``Drivers`` 路径。 +4. 在附加参数区域设置 ``--compile-commands-dir=/project/build``。 +5. 点击 ``Apply and Close``。 + + .. image:: ../../../media/clangd/clangd_config.png + +创建新项目时，会默认生成一个 ``.clangd`` 配置文件，并带有如下参数。 + +如果处理的是现有项目，请在项目根目录处创建 ``.clangd`` 文件并添加如下内容。 + +.. code-block:: yaml + + CompileFlags: + CompilationDatabase: build + Remove: [-m*, -f*] + +如何解决在浏览 ESP-IDF 组件时出现的 "Unknown Argument" 错误 +----------------------------------------------------------- + +如果在浏览 ESP-IDF 组件源码时看到如下错误标记： + +.. code-block:: none + + Multiple markers at this line + - Unknown argument: '-fno-tree-switch-conversion' [drv_unknown_argument] + - Unknown argument: '-fno-shrink-wrap' [drv_unknown_argument] + - Unknown argument: '-fstrict-volatile-bitfields' [drv_unknown_argument] + +请按以下步骤修复： + +1. 下载脚本 `fix_compile_commands.py `_。 + +2. 在项目的 post build 阶段中调用该脚本。以下为 `CMakeLists.txt `_ 示例： + + .. code-block:: cmake + + if(EXISTS "${CMAKE_SOURCE_DIR}/fix_compile_commands.py") + add_custom_target( + fix_clangd ALL + COMMAND ${CMAKE_COMMAND} -E echo "Running fix_compile_commands.py..." + COMMAND ${CMAKE_COMMAND} -E env python3 ${CMAKE_SOURCE_DIR}/fix_compile_commands.py + COMMENT "Cleaning compile_commands.json for clangd" + VERBATIM + ) + endif() + +3. 运行构建，该脚本会从 ``compile_commands.json`` 文件中移除 clangd 无法识别的 ``-m*`` 和 ``-f*`` 标志。 + +4. 现在浏览 ESP-IDF 组件源码将不会出现报错。 + +禁用 CDT 索引器 +--------------- + +在 Espressif-IDE 3.0.0 及更高版本中，默认禁用 CDT 索引器，代码分析由 LSP 索引器服务器执行。 + +如果 CDT 索引器因为某些原因未被自动禁用，可参照下列步骤手动将其禁用。 + +1. 前往 ``Window`` > ``Preferences`` > ``C/C++`` > ``Indexer``。 +2. 取消勾选 ``Enable Indexer`` 选项，然后点击 ``Apply and Close``。 + + .. image:: ../../../media/clangd/cdt_indexer_disable.png