From 3674c3ee0496de12da1420daa1b6d41c50de3c60 Mon Sep 17 00:00:00 2001 From: shenmengjing Date: Wed, 13 Nov 2024 14:08:04 +0800 Subject: [PATCH] docs: Provide CN translation for settings.rst --- docs_espressif/en/settings.rst | 461 ++++++++++++++++-------------- docs_espressif/zh_CN/settings.rst | 289 +++++++++++++++++++ 2 files changed, 535 insertions(+), 215 deletions(-) create mode 100644 docs_espressif/zh_CN/settings.rst diff --git a/docs_espressif/en/settings.rst b/docs_espressif/en/settings.rst index 5a1dc9903..a01e51832 100644 --- a/docs_espressif/en/settings.rst +++ b/docs_espressif/en/settings.rst @@ -1,258 +1,289 @@ ESP-IDF Settings -======================= +================ -This extension contributes the following settings that can be later updated in settings.json or from VS Code Settings Preference Menu by: +:link_to_translation:`zh_CN:[中文]` + +This extension contributes the following settings that can be later updated in ``settings.json`` or from VS Code Settings Preference Menu by: - Navigate to **View** > **Command Palette**. -- Type **Preferences: Open Settings (UI)** and select the command to open the Setting management window. +- Type **Preferences: Open Settings (UI)** and select the command to open the setting management window. .. note:: - Please consider that ``~``, ``%VARNAME%`` and ``$VARNAME`` are not recognized when set on ANY of this extension configuration settings. You can instead set any environment variable in the path using a ``${env:VARNAME}`` such as ``${env:HOME}`` or you can refer to other configuration parameter path with ``${config:SETTINGID}`` such as ``${config:idf.espIdfPath}``. + + Please note that ``~``, ``%VARNAME%`` and ``$VARNAME`` are not recognized when set on ANY of this extension configuration settings. Instead, you can set any environment variable in the path using ``${env:VARNAME}``, such as ``${env:HOME}``, or refer to other configuration parameter path with ``${config:SETTINGID}``, such as ``${config:idf.espIdfPath}``. The **idf.saveScope** allows you to specify where to save settings when using commands such as **Set Espressif Device Target** and other commands. Possible values are Global (User Settings), Workspace and WorkspaceFolder. Use the **Select where to Save Configuration Settings** command to choose where to save settings when using this extension commands. .. note:: - All settings can be applied to Global (User Settings), Workspace and WorkspaceFolder unless Scope is specified. + + All settings can be applied to Global (User Settings), Workspace and WorkspaceFolder unless Scope is specified. ESP-IDF Specific Settings ------------------------------ +------------------------- These are the configuration settings that ESP-IDF extension contributes to your Visual Studio Code editor settings. -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| Setting ID | Description | -+===================================+===========================================================================================+ -| **idf.buildPath** | Custom build directory name for extension commands. (Default: \${workspaceFolder}/build) | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.buildPathWin** | Custom build directory name for extension commands. (Default: \${workspaceFolder}\\build) | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.sdkconfigFilePath** | Absolute path for sdkconfig file | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.sdkconfigDefaults** | List of sdkconfig default values for initial build configuration | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.cmakeCompilerArgs** | Arguments for CMake compilation task | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.customExtraVars** | Variables to be added to system environment variables | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.gitPath** | Path to git executable | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.gitPathWin** | Path to git executable in Windows | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.enableCCache** | Enable CCache on build task (make sure CCache is in PATH) | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.enableIdfComponentManager** | Enable IDF Component manager in build command | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.espIdfPath** | Path to locate ESP-IDF framework (IDF_PATH) | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.espIdfPathWin** | Path to locate ESP-IDF framework in Windows (IDF_PATH) | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.ninjaArgs** | Arguments for Ninja build task | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.pythonInstallPath** | System python absolute path used to compute ESP-IDF python virtual environment | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.toolsPath** | Path to locate ESP-IDF Tools (IDF_TOOLS_PATH) | -+-----------------------------------+-------------------------------------------------------------------------------------------+ -| **idf.toolsPathWin** | Path to locate ESP-IDF Tools in Windows (IDF_TOOLS_PATH) | -+-----------------------------------+-------------------------------------------------------------------------------------------+ - +.. list-table:: + :widths: 10 20 + :header-rows: 1 + + * - Setting ID + - Description + * - idf.buildPath + - Custom build directory name for extension commands (Default: \${workspaceFolder}/build) + * - idf.buildPathWin + - Custom build directory name for extension commands (Default: \${workspaceFolder}\\build) + * - idf.sdkconfigFilePath + - Absolute path for the sdkconfig file + * - idf.sdkconfigDefaults + - List of sdkconfig default values for initial build configuration + * - idf.cmakeCompilerArgs + - Arguments for CMake compilation task + * - idf.customExtraVars + - Variables to be added to system environment variables + * - idf.gitPath + - Path to the Git executable + * - idf.gitPathWin + - Path to the Git executable in Windows + * - idf.enableCCache + - Enable CCache in build task (make sure CCache is in PATH) + * - idf.enableIdfComponentManager + - Enable IDF Component manager in build command + * - idf.espIdfPath + - Path to locate ESP-IDF framework (IDF_PATH) + * - idf.espIdfPathWin + - Path to locate ESP-IDF framework in Windows (IDF_PATH) + * - idf.ninjaArgs + - Arguments for Ninja build task + * - idf.pythonInstallPath + - System Python absolute path used to compute ESP-IDF Python virtual environment + * - idf.toolsPath + - Path to locate ESP-IDF Tools (IDF_TOOLS_PATH) + * - idf.toolsPathWin + - Path to locate ESP-IDF Tools in Windows (IDF_TOOLS_PATH) This is how the extension uses them: -1. **idf.customExtraVars** stores any custom environment variable such as OPENOCD_SCRIPTS, which is the openOCD scripts directory used in OpenOCD server startup. These variables are loaded to this extension commands process environment variables, choosing the extension variable if available, else extension commands will try to use what is already in your system PATH. **This doesn't modify your system environment outside Visual Studio Code.** -2. **idf.espIdfPath** (or **idf.espIdfPathWin** in Windows) is used to store ESP-IDF directory path within our extension. We override Visual Studio Code process IDF_PATH if this value is available. **This doesn't modify your system environment outside Visual Studio Code.**. It is also used to compute the list of ESP-IDF tools to add to environment variable PATH and the python virtual environment path together from **idf.toolsPath** and **idf.pythonInstallPath**. -3. **idf.pythonInstallPath** is the system python absolute path used to compute ESP-IDF python virtual environment from **idf.toolsPath** and **idf.espIdfPath** where ESP-IDF python packages will be installed and used. +1. **idf.customExtraVars** stores any custom environment variable such as OPENOCD_SCRIPTS, which is the openOCD scripts directory used in OpenOCD server startup. These variables are loaded to this extension command's process environment variables, choosing the extension variable if available, else extension commands will try to use what is already in your system PATH. **This doesn't modify your system environment outside Visual Studio Code.** +2. **idf.espIdfPath** (or **idf.espIdfPathWin** in Windows) is used to store ESP-IDF directory path within our extension. We override Visual Studio Code process IDF_PATH if this value is available. **This doesn't modify your system environment outside Visual Studio Code.**. It is also used to compute the list of ESP-IDF tools to add to environment variable PATH and the Python virtual environment path together from **idf.toolsPath** and **idf.pythonInstallPath**. +3. **idf.pythonInstallPath** is the system Python absolute path used to compute ESP-IDF Python virtual environment from **idf.toolsPath** and **idf.espIdfPath** where ESP-IDF Python packages will be installed and used. 4. **idf.gitPath** (or **idf.gitPathWin** in Windows) is used in the extension to clone ESP-IDF master version or the additional supported frameworks such as ESP-ADF, ESP-MDF and Arduino-ESP32. -5. **idf.toolsPath** (or **idf.toolsPathWin** in Windows) is used to compute the list of ESP-IDF tools to add to environment variable PATH and the python virtual environment path together from **idf.pythonInstallPath** and **idf.espIdfPath**. +5. **idf.toolsPath** (or **idf.toolsPathWin** in Windows) is used to compute the list of ESP-IDF tools to add to environment variable PATH and the Python virtual environment path together from **idf.pythonInstallPath** and **idf.espIdfPath**. + +.. note:: -> **NOTE**: From Visual Studio Code extension context, we can't modify your system PATH or any other environment variable. We use a modified process environment in all of this extension tasks and child processes which should not affect any other system process or extension. Please review the content of **idf.customExtraVars** in case you have issues with other extensions. + From Visual Studio Code extension context, we can't modify your system PATH or any other environment variable. We use a modified process environment in all of this extension tasks and child processes which should not affect any other system process or extension. Please review the content of **idf.customExtraVars** in case you have issues with other extensions. Board/Chip Specific Settings -------------------------------------------------------------------------- - -These settings are specific to the ESP32 Chip/Board - -+----------------------------------------------------+----------------------------------------------------------------------------------------+ -| Setting | Description | -+====================================================+========================================================================================+ -| **idf.flashBaudRate** | Flash Baud rate | -+----------------------------------------------------+----------------------------------------------------------------------------------------+ -| **idf.monitorBaudRate** | Monitor Baud Rate (Empty by default to use SDKConfig CONFIG_ESP_CONSOLE_UART_BAUDRATE) | -+----------------------------------------------------+----------------------------------------------------------------------------------------+ -| **idf.openOcdConfigs** | Configuration Files for OpenOCD. Relative to OPENOCD_SCRIPTS folder | -+----------------------------------------------------+----------------------------------------------------------------------------------------+ -| **idf.openOcdLaunchArgs** | Launch Arguments for OpenOCD before idf.openOcdDebugLevel and idf.openOcdConfigs | -+----------------------------------------------------+----------------------------------------------------------------------------------------+ -| **idf.openOcdDebugLevel** | Set openOCD Debug Level (0-4) Default: 2 | -+----------------------------------------------------+----------------------------------------------------------------------------------------+ -| **idf.port** | Path of Selected Device port | -+----------------------------------------------------+----------------------------------------------------------------------------------------+ -| **idf.portWin** | Path of Selected Device Port in Windows | -+----------------------------------------------------+----------------------------------------------------------------------------------------+ -| **idf.enableSerialPortChipIdRequest** | Enable detecting the chip id and show on serial port selection list | -+----------------------------------------------------+----------------------------------------------------------------------------------------+ -| **idf.useSerialPortVendorProductFilter** | Enable use of idf.usbSerialPortFilters list to filter serial port devices list | -+----------------------------------------------------+----------------------------------------------------------------------------------------+ -| **idf.usbSerialPortFilters** | USB productID and vendorID list to filter known Espressif devices | -+----------------------------------------------------+----------------------------------------------------------------------------------------+ -| **openocd.jtag.command.force_unix_path_separator** | Forced to Use ``/`` as Path sep. for Win32 Based OS Instead of ``\\`` | -+----------------------------------------------------+----------------------------------------------------------------------------------------+ -| **idf.svdFilePath** | SVD File Absolute Path to Resolve Chip Debug Peripheral Tree view | -+----------------------------------------------------+----------------------------------------------------------------------------------------+ +---------------------------- + +These settings are specific to the ESP32 Chip/Board. + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Setting + - Description + * - **idf.flashBaudRate** + - Flash Baud Rate + * - **idf.monitorBaudRate** + - Monitor Baud Rate (Empty by default to use SDKConfig ``CONFIG_ESP_CONSOLE_UART_BAUDRATE``) + * - **idf.openOcdConfigs** + - Configuration files for OpenOCD, relative to ``OPENOCD_SCRIPTS`` folder + * - **idf.openOcdLaunchArgs** + - Launch arguments for OpenOCD before ``idf.openOcdDebugLevel`` and ``idf.openOcdConfigs`` + * - **idf.openOcdDebugLevel** + - Set OpenOCD Debug Level (0-4) Default: 2 + * - **idf.port** + - Path of selected device port + * - **idf.portWin** + - Path of selected device port in Windows + * - **idf.enableSerialPortChipIdRequest** + - Enable detecting the chip ID and show on serial port selection list + * - **idf.useSerialPortVendorProductFilter** + - Enable use of ``idf.usbSerialPortFilters`` list to filter serial port devices list + * - **idf.usbSerialPortFilters** + - USB productID and vendorID list to filter known Espressif devices + * - **openocd.jtag.command.force_unix_path_separator** + - Forced to use ``/`` instead of ``\\`` as path separator for Win32 based OS + * - **idf.svdFilePath** + - SVD file absolute path to resolve chip debug peripheral tree view This is how the extension uses them: -1. **idf.flashBaudRate** is the baud rate value used for the **ESP-IDF: Flash your Project** command and [ESP-IDF Debug](./DEBUGGING.md). -2. **idf.monitorBaudRate** is the ESP-IDF Monitor baud rate value and fallback from your project's skdconfig ``CONFIG_ESPTOOLPY_MONITOR_BAUD`` (idf.py monitor' baud rate). This value can also be override by setting the environment variable ``IDF_MONITOR_BAUD`` or ``MONITORBAUD`` in your system environment variables or this extension's **idf.customExtraVars** configuration setting. -3. **idf.openOcdConfigs** is used to store an string array of OpenOCD scripts directory relative path config files to use with OpenOCD server. (Example: ``["interface/ftdi/esp32_devkitj_v1.cfg", "board/esp32-wrover.cfg"]``). More information `OpenOCD JTAG Target configuration `_. +1. **idf.flashBaudRate** is the baud rate value used for the **ESP-IDF: Flash your Project** command and `Debugging `_. +2. **idf.monitorBaudRate** is the ESP-IDF Monitor baud rate value and fallback from your project's sdkconfig ``CONFIG_ESPTOOLPY_MONITOR_BAUD`` (idf.py monitor' baud rate). This value can also be override by setting the environment variable ``IDF_MONITOR_BAUD`` or ``MONITORBAUD`` in your system environment variables or this extension's **idf.customExtraVars** configuration setting. +3. **idf.openOcdConfigs** is used to store an string array of OpenOCD scripts directory relative path config files to use with OpenOCD server. (e.g.，``["interface/ftdi/esp32_devkitj_v1.cfg", "board/esp32-wrover.cfg"]``). More information can be found in `OpenOCD JTAG Target Configuration `_. 4. **idf.port** (or **idf.portWin** in Windows) is used as the serial port value for the extension commands. -5. **idf.openOcdDebugLevel**: Log level for OpenOCD Server output from 0 to 4. -6. **idf.openOcdLaunchArgs**: Launch arguments string array for OpenOCD. The resulting OpenOCD launch command looks like this: ``openocd -d${idf.openOcdDebugLevel} -f ${idf.openOcdConfigs} ${idf.openOcdLaunchArgs}``. +5. **idf.openOcdDebugLevel** is the log level for OpenOCD server output from 0 to 4. +6. **idf.openOcdLaunchArgs** is the launch arguments string array for OpenOCD. The resulting OpenOCD launch command looks like this: ``openocd -d${idf.openOcdDebugLevel} -f ${idf.openOcdConfigs} ${idf.openOcdLaunchArgs}``. .. note:: - * When you use the command **ESP-IDF: Set Espressif Device Target** it will override the current sdkconfig IDF_TARGET with selected Espressif chip and **idf.openOcdConfigs** with its default OpenOCD Configuration Files. - * If you want to customize the **idf.openOcdConfigs** alone, you can use the **ESP-IDF: Select OpenOCD Board Configuration** or modify your settings.json directly. + + * When using the command **ESP-IDF: Set Espressif Device Target**, it will override the current sdkconfig IDF_TARGET with selected Espressif chip, and it will also update **idf.openOcdConfigs** with its default OpenOCD configuration files. + * To customize the **idf.openOcdConfigs** alone, you can use the **ESP-IDF: Select OpenOCD Board Configuration** or modify your ``settings.json`` directly. Code Coverage Specific Settings -------------------------------------------------------------------------- - -These settings are used to configure the Code Coverage colors. - -+--------------------------------+--------------------------------------------------------------------------+ -| Setting ID | Description | -+================================+==========================================================================+ -| **idf.coveredLightTheme** | Background color for covered lines in light theme for gcov coverage | -+--------------------------------+--------------------------------------------------------------------------+ -| **idf.coveredDarkTheme** | Background color for covered lines in dark theme for gcov coverage | -+--------------------------------+--------------------------------------------------------------------------+ -| **idf.partialLightTheme** | Background color for partially covered lines in light theme for gcov | -| | coverage | -+--------------------------------+--------------------------------------------------------------------------+ -| **idf.partialDarkTheme** | Background color for partially covered lines in dark theme for gcov | -| | coverage | -+--------------------------------+--------------------------------------------------------------------------+ -| **idf.uncoveredLightTheme** | Background color for uncovered lines in light theme for gcov coverage | -+--------------------------------+--------------------------------------------------------------------------+ -| **idf.uncoveredDarkTheme** | Background color for uncovered lines in dark theme for gcov coverage | -+--------------------------------+--------------------------------------------------------------------------+ +------------------------------- + +These settings are used to configure the code coverage colors. + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Setting ID + - Description + * - **idf.coveredLightTheme** + - Background color for covered lines in light theme for gcov coverage + * - **idf.coveredDarkTheme** + - Background color for covered lines in dark theme for gcov coverage + * - **idf.partialLightTheme** + - Background color for partially covered lines in light theme for gcov coverage + * - **idf.partialDarkTheme** + - Background color for partially covered lines in dark theme for gcov coverage + * - **idf.uncoveredLightTheme** + - Background color for uncovered lines in light theme for gcov coverage + * - **idf.uncoveredDarkTheme** + - Background color for uncovered lines in dark theme for gcov coverage Extension Behaviour Settings -------------------------------------------------------------------------- - -+------------------------------------------+------------------------------------------------------------------------------------+ -| Setting ID | Description | -+==========================================+====================================================================================+ -| **idf.enableUpdateSrcsToCMakeListsFile** | Enable update source files in CMakeLists.txt (default ``true``) | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.flashType** | Preferred flash method. DFU, UART or JTAG | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.launchMonitorOnDebugSession** | Launch ESP-IDF Monitor along with ESP-IDF Debug session | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.notificationMode** | ESP-IDF extension notifications and output focus mode. (default ``All``) | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.showOnboardingOnInit** | Show ESP-IDF Configuration Window on extension activation | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.saveScope** | Where to save extension settings | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.saveBeforeBuild** | Save all the edited files before building (default ``true``) | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.useIDFKconfigStyle** | Enable style validation for Kconfig files | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.telemetry** | Enable telemetry | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.deleteComponentsOnFullClean** | Delete ``managed_components`` on Full Clean Project command (default ``false``) | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.monitorNoReset** | Enable no-reset flag to IDF Monitor (default ``false``) | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.monitorEnableTimestamps** | Enable timestamps in IDF Monitor (default ``false``) | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.monitorCustomTimestampFormat** | Custom timestamp format in IDF Monitor | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.monitorStartDelayBeforeDebug** | Delay to start debug session after IDF monitor execution | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.enableStatusBar** | Show or hide the extension status bar items | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.enableSizeTaskAfterBuildTask** | Enable IDF Size Task to be executed after IDF Build Task | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.customTerminalExecutable** | Absolute path to shell terminal executable to use (default to VS Code Terminal) | -+------------------------------------------+------------------------------------------------------------------------------------+ -| **idf.customTerminalExecutableArgs** | Shell arguments for idf.customTerminalExecutable | -+------------------------------------------+------------------------------------------------------------------------------------+ +---------------------------- + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Setting ID + - Description + * - **idf.enableUpdateSrcsToCMakeListsFile** + - Enable updating source files in ``CMakeLists.txt`` (default ``true``) + * - **idf.flashType** + - Preferred flash method. DFU, UART or JTAG + * - **idf.launchMonitorOnDebugSession** + - Launch ESP-IDF Monitor along with ESP-IDF debug session + * - **idf.notificationMode** + - ESP-IDF extension notifications and output focus mode. (default ``All``) + * - **idf.showOnboardingOnInit** + - Show ESP-IDF configuration window on extension activation + * - **idf.saveScope** + - Where to save extension settings + * - **idf.saveBeforeBuild** + - Save all the edited files before building (default ``true``) + * - **idf.useIDFKconfigStyle** + - Enable style validation for Kconfig files + * - **idf.telemetry** + - Enable telemetry + * - **idf.deleteComponentsOnFullClean** + - Delete ``managed_components`` on **Full Clean Project** command (default ``false``) + * - **idf.monitorNoReset** + - Enable no-reset flag to IDF Monitor (default ``false``) + * - **idf.monitorEnableTimestamps** + - Enable timestamps in IDF Monitor (default ``false``) + * - **idf.monitorCustomTimestampFormat** + - Custom timestamp format in IDF Monitor + * - **idf.monitorStartDelayBeforeDebug** + - Delay to start debug session after IDF monitor execution + * - **idf.enableStatusBar** + - Show or hide the extension status bar items + * - **idf.enableSizeTaskAfterBuildTask** + - Enable IDF Size Task to be executed after IDF Build Task + * - **idf.customTerminalExecutable** + - Absolute path to shell terminal executable to use (default to VS Code Terminal) + * - **idf.customTerminalExecutableArgs** + - Shell arguments for idf.customTerminalExecutable Custom Tasks for Build and Flash Tasks -------------------------------------------------------------------------- - -+----------------------+--------------------------------------------------------------+ -| Setting ID | Description | -+======================+==============================================================+ -| **idf.customTask** | Custom task to execute with **ESP-IDF: Execute Custom Task** | -+----------------------+--------------------------------------------------------------+ -| **idf.preBuildTask** | Command string to execute before build task | -+----------------------+--------------------------------------------------------------+ -| **idf.postBuildTask**| Command string to execute after build task | -+----------------------+--------------------------------------------------------------+ -| **idf.preFlashTask** | Command string to execute before flash task | -+----------------------+--------------------------------------------------------------+ -| **idf.postFlashTask**| Command string to execute after flash task | -+----------------------+--------------------------------------------------------------+ +-------------------------------------- + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Setting ID + - Description + * - **idf.customTask** + - Custom task to execute with **ESP-IDF: Execute Custom Task** + * - **idf.preBuildTask** + - Command string to execute before build task + * - **idf.postBuildTask** + - Command string to execute after build task + * - **idf.preFlashTask** + - Command string to execute before flash task + * - **idf.postFlashTask** + - Command string to execute after flash task QEMU Specific Settings -------------------------------------------------------------------------- +---------------------- + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Setting ID + - Description + * - **idf.qemuTcpPort** + - QEMU TCP port for serial communication -+----------------------+----------------------------------------+ -| Setting ID | Description | -+======================+========================================+ -| **idf.qemuTcpPort** | QEMU tcp port for serial communication | -+----------------------+----------------------------------------+ Log Tracing Specific Settings -------------------------------------------------------------------------- - -+-----------------------+------------------------------------------+ -| Setting | Description | -+=======================+==========================================+ -| **trace.poll_period** | poll_period will be set for the apptrace | -+-----------------------+------------------------------------------+ -| **trace.trace_size** | trace_size will set for the apptrace | -+-----------------------+------------------------------------------+ -| **trace.stop_tmo** | stop_tmo will be set for the apptrace | -+-----------------------+------------------------------------------+ -| **trace.wait4halt** | wait4halt will be set for the apptrace | -+-----------------------+------------------------------------------+ -| **trace.skip_size** | skip_size will be set for the apptrace | -+-----------------------+------------------------------------------+ - -Other Frameworks Specific Settings -------------------------------------------------------------------------- - -These settings allow to support additional frameworks together with ESP-IDF: - -+-----------------------------+-----------------------------------------------------------------+ -| Setting ID | Description | -+=============================+=================================================================+ -| **idf.espAdfPath** | Path to locate ESP-ADF framework (ADF_PATH) | -+-----------------------------+-----------------------------------------------------------------+ -| **idf.espAdfPathWin** | Path to locate ESP-ADF framework in Windows (ADF_PATH) | -+-----------------------------+-----------------------------------------------------------------+ -| **idf.espMdfPath** | Path to locate ESP-MDF framework (MDF_PATH) | -+-----------------------------+-----------------------------------------------------------------+ -| **idf.espMdfPathWin** | Path to locate ESP-MDF framework in Windows (MDF_PATH) | -+-----------------------------+-----------------------------------------------------------------+ -| **idf.espMatterPath** | Path to locate ESP-Matter framework (ESP_MATTER_PATH) | -+-----------------------------+-----------------------------------------------------------------+ -| **idf.espRainmakerPath** | Path to locate ESP-Rainmaker framework in Windows (RMAKER_PATH) | -+-----------------------------+-----------------------------------------------------------------+ -| **idf.espRainmakerPathWin** | Path to locate ESP-Rainmaker framework in Windows (RMAKER_PATH) | -+-----------------------------+-----------------------------------------------------------------+ -| **idf.sbomFilePath** | Path to create ESP-IDF SBOM report | -+-----------------------------+-----------------------------------------------------------------+ - -Use of Environment Variables in ESP-IDF settings.json and tasks.json -------------------------------------------------------------------------- - -Environment (env) variables and other ESP-IDF settings (config) current values strings can be used in other ESP-IDF setting as ``${env:VARNAME}`` and ``${config:ESPIDFSETTING}``, respectively. - -Example : If you want to use ``"~/esp/esp-idf"`` you can set the value of **idf.espIdfPath** to ``"${env:HOME}/esp/esp-idf"``. +----------------------------- + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Setting + - Description + * - **trace.poll_period** + - poll_period will be set for the apptrace + * - **trace.trace_size** + - trace_size will set for the apptrace + * - **trace.stop_tmo** + - stop_tmo will be set for the apptrace + * - **trace.wait4halt** + - wait4halt will be set for the apptrace + * - **trace.skip_size** + - skip_size will be set for the apptrace + + +Other Frameworks' Specific Settings +----------------------------------- + +These settings support additional frameworks together with ESP-IDF: + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Setting ID + - Description + * - **idf.espAdfPath** + - Path to locate ESP-ADF framework (ADF_PATH) + * - **idf.espAdfPathWin** + - Path to locate ESP-ADF framework in Windows (ADF_PATH) + * - **idf.espMdfPath** + - Path to locate ESP-MDF framework (MDF_PATH) + * - **idf.espMdfPathWin** + - Path to locate ESP-MDF framework in Windows (MDF_PATH) + * - **idf.espMatterPath** + - Path to locate ESP-Matter framework (ESP_MATTER_PATH) + * - **idf.espRainmakerPath** + - Path to locate ESP-Rainmaker framework in Windows (RMAKER_PATH) + * - **idf.espRainmakerPathWin** + - Path to locate ESP-Rainmaker framework in Windows (RMAKER_PATH) + * - **idf.sbomFilePath** + - Path to create ESP-IDF SBOM report + + +Use of Environment Variables in ESP-IDF ``settings.json`` and ``tasks.json`` +---------------------------------------------------------------------------- + +Environment (env) variables and other ESP-IDF settings (config) can be referenced in ESP-IDF settings using the syntax ``${env:VARNAME}`` and ``${config:ESPIDFSETTING}``, respectively. + +For example, to use ``"~/esp/esp-idf"``, set the value of **idf.espIdfPath** to ``"${env:HOME}/esp/esp-idf"``. diff --git a/docs_espressif/zh_CN/settings.rst b/docs_espressif/zh_CN/settings.rst new file mode 100644 index 000000000..5b78233a7 --- /dev/null +++ b/docs_espressif/zh_CN/settings.rst @@ -0,0 +1,289 @@ +ESP-IDF 设置 +============ + +:link_to_translation:`en:[English]` + +此扩展提供一些特殊设置，可在 ``settings.json`` 文件中进行更新，或按照下列步骤在 VS Code 设置首选项菜单栏中更新： + +- 点击 **查看** > **命令面板**。 + +- 输入 **首选项：打开设置 (UI)**，点击该命令，打开设置管理窗口。 + +.. note:: + + 请注意，配置此扩展时，``~``、``%VARNAME%`` 和 ``$VARNAME`` 都无法被识别到。请使用 ``${env:VARNAME}`` 来设置路径中的环境变量，例如 ``${env:HOME}``。也可以通过 ``${config:SETTINGID}`` 来引用其他配置参数，例如 ``${config:idf.espIdfPath}``。 + +在运行 **设置乐鑫设备目标** 等命令时，**idf.saveScope** 可指定保存设置的位置。可选择将设置保存在全局（用户设置）、工作区或工作区文件夹。请使用 **选择设置存储范围** 命令来选择保存设置的位置。 + +.. note:: + + 除非指定了作用域 (Scope)，所有设置都可以应用于全局（用户设置）、工作区或工作区文件夹。 + +ESP-IDF 相关设置 +---------------- + +下表展示了 ESP-IDF 扩展为 VS Code 编辑器设置提供的配置选项。 + +.. list-table:: + :widths: 10 20 + :header-rows: 1 + + * - 设置 ID + - 描述 + * - idf.buildPath + - 扩展命令的自定义构建目录名称（默认值：\${workspaceFolder}/build） + * - idf.buildPathWin + - 扩展命令的自定义构建目录名称（默认值：\${workspaceFolder}\\build） + * - idf.sdkconfigFilePath + - sdkconfig 文件的绝对路径 + * - idf.sdkconfigDefaults + - 初始构建配置的 sdkconfig 默认值列表 + * - idf.cmakeCompilerArgs + - CMake 编译任务的参数 + * - idf.customExtraVars + - 要添加到系统环境变量中的变量 + * - idf.gitPath + - git 可执行文件的路径 + * - idf.gitPathWin + - Windows 系统中 git 可执行文件的路径 + * - idf.enableCCache + - 在构建任务中启用 CCache（确保 CCache 在 PATH 中） + * - idf.enableIdfComponentManager + - 在构建命令中启用 IDF 组件管理器 + * - idf.espIdfPath + - ESP-IDF 框架的位置路径 (IDF_PATH) + * - idf.espIdfPathWin + - Windows 系统中 ESP-IDF 框架的位置路径 (IDF_PATH) + * - idf.ninjaArgs + - Ninja 构建任务的参数 + * - idf.pythonInstallPath + - 用于构建 ESP-IDF Python 虚拟环境的系统 Python 绝对路径 + * - idf.toolsPath + - ESP-IDF 工具的位置路径 (IDF_TOOLS_PATH) + * - idf.toolsPathWin + - Windows 系统中 ESP-IDF 工具的位置路径 (IDF_TOOLS_PATH) + +扩展将按照以下方式使用上述设置： + +1. **idf.customExtraVars** 用于存储自定义环境变量，例如 OPENOCD_SCRIPTS，用于指定启动 OpenOCD 服务器时所需脚本文件的目录路径。这些变量会加载到扩展命令的进程环境变量中，优先使用扩展变量，如果没有，则扩展命令会尝试使用系统 PATH 中已有的设置。**该配置项不会改变 VS Code 之外的系统环境。** +2. **idf.espIdfPath**（Windows 系统中为 **idf.espIdfPathWin**）用于在扩展中存储 ESP-IDF 目录路径。如果该值已配置，则 VS Code 进程中原有的 IDF_PATH 会被覆盖。**该配置项不会改变 VS Code 之外的系统环境。** 此外，扩展使用 **idf.espIdfPath**，结合 **idf.toolsPath** 和 **idf.pythonInstallPath**，来确定要添加到环境变量 PATH 中的 ESP-IDF 工具路径和 Python 虚拟环境路径。 +3. **idf.pythonInstallPath** 是系统 Python 的绝对路径，基于 **idf.toolsPath** 和 **idf.espIdfPath** 来生成 ESP-IDF Python 虚拟环境路径。创建虚拟环境后，ESP-IDF 的 Python 包将在该环境中安装和使用。 +4. **idf.gitPath**（Windows 系统中为 **idf.gitPathWin**）在扩展中用于克隆 ESP-IDF master 版本及其他支持的框架，如 ESP-ADF、ESP-MDF 和 Arduino-ESP32。 +5. **idf.toolsPath**（Windows 系统中为 **idf.toolsPathWin**）用于结合 **idf.toolsPath** 和 **idf.pythonInstallPath** 来确定要添加到环境变量 PATH 中的 ESP-IDF 工具路径和 Python 虚拟环境路径。 + +.. note:: + + 在 VS Code 扩展中，系统 PATH 及其他环境变量是无法修改的。在扩展的所有任务和子进程中，本扩展使用的是修改后的进程环境，且不应影响其他系统进程及扩展。请检查 **idf.customExtraVars** 的配置，以防与其他扩展发生冲突。 + +开发板/芯片相关设置 +-------------------- + +以下是针对 ESP32 芯片/开发板的配置项。 + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - 设置 + - 描述 + * - **idf.flashBaudRate** + - 烧录速率 + * - **idf.monitorBaudRate** + - 监视器速率（默认留空，通过 SDKConfig 中的 ``CONFIG_ESP_CONSOLE_UART_BAUDRATE`` 进行配置） + * - **idf.openOcdConfigs** + - OpenOCD 配置文件路径，相对路径基于 ``OPENOCD_SCRIPTS`` 文件夹 + * - **idf.openOcdLaunchArgs** + - OpenOCD 启动参数，位于 ``idf.openOcdDebugLevel`` 和 ``idf.openOcdConfigs`` 之前 + * - **idf.openOcdDebugLevel** + - 设置 OpenOCD 调试级别 (0-4)，默认值为 2 + * - **idf.port** + - 选择的设备端口路径 + * - **idf.portWin** + - Windows 系统中选择的设备端口路径 + * - **idf.enableSerialPortChipIdRequest** + - 启用芯片 ID 检测功能，并在串口选择列表中显示 ID + * - **idf.useSerialPortVendorProductFilter** + - 启用 ``idf.usbSerialPortFilters`` 列表以过滤串口设备列表 + * - **idf.usbSerialPortFilters** + - 用于过滤已知乐鑫设备的 USB productID 和 vendorID 列表 + * - **openocd.jtag.command.force_unix_path_separator** + - 强制在 Windows 操作系统中使用 ``/`` 作为路径分隔符，而不是 ``\\`` + * - **idf.svdFilePath** + - SVD 文件的绝对路径，用于解析芯片在调试器中的外设树视图 + +扩展将按照以下方式使用上述设置： + +1. **idf.flashBaudRate** 是用于 **ESP-IDF：烧录项目** 命令和 `Debugging `_ 的烧录速率。 +2. **idf.monitorBaudRate** 是 ESP-IDF 的监视器速率值，默认会从项目的 sdkconfig 配置项``CONFIG_ESPTOOLPY_MONITOR_BAUD``（即 idf.py monitor 命令的波特率）中获取该值作为回退值 (fallback)。该值也可以通过系统环境变量中的 ``IDF_MONITOR_BAUD`` 或 ``MONITORBAUD`` 进行覆盖，或者在扩展的 **idf.customExtraVars** 配置项中指定。 +3. **idf.openOcdConfigs** 用于存储一组 OpenOCD 脚本目录相对路径配置文件的字符串数组，以便与 OpenOCD 服务器一同使用。（例如，``["interface/ftdi/esp32_devkitj_v1.cfg", "board/esp32-wrover.cfg"]``）。详情请参阅 `OpenOCD JTAG 目标配置 `_。 +4. **idf.port** （Windows 系统中为 **idf.portWin**）用作扩展命令的串口值。 +5. **idf.openOcdDebugLevel** 是 OpenOCD 服务器输出的日志级别，范围为 0 到 4。 +6. **idf.openOcdLaunchArgs** 是用于配置 OpenOCD 启动的参数字符串数组。生成的 OpenOCD 启动命令格式如下：``openocd -d${idf.openOcdDebugLevel} -f ${idf.openOcdConfigs} ${idf.openOcdLaunchArgs}``。 + +.. note:: + + * 使用 **ESP-IDF：设置乐鑫设备目标** 命令时，当前 sdkconfig 文件中的 IDF_TARGET 配置项将被选中的乐鑫芯片所覆盖，并将 **idf.openOcdConfigs** 设置为芯片默认的 OpenOCD 配置文件。 + * 如果只想自定义 **idf.openOcdConfigs**，可以使用 **ESP-IDF：选择 OpenOCD 开发板配置** 命令，或直接修改 ``settings.json`` 文件。 + +代码覆盖率相关设置 +------------------ + +以下列表展示了代码覆盖率的颜色配置。 + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - 设置 ID + - 描述 + * - **idf.coveredLightTheme** + - 浅色主题下 gcov 代码覆盖率报告中覆盖行的背景颜色 + * - **idf.coveredDarkTheme** + - 深色主题下 gcov 代码覆盖率报告中覆盖行的背景颜色 + * - **idf.partialLightTheme** + - 浅色主题下 gcov 代码覆盖率报告中部分覆盖行的背景颜色 + * - **idf.partialDarkTheme** + - 深色主题下 gcov 代码覆盖率报告中部分覆盖行的背景颜色 + * - **idf.uncoveredLightTheme** + - 浅色主题下 gcov 代码覆盖率报告中未覆盖行的背景颜色 + * - **idf.uncoveredDarkTheme** + - 深色主题下 gcov 代码覆盖率报告中未覆盖行的背景颜色 + + +扩展行为设置 +------------ + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - 设置 ID + - 描述 + * - **idf.enableUpdateSrcsToCMakeListsFile** + - 启用在 ``CMakeLists.txt`` 文件中更新源文件的功能（该选项默认启用） + * - **idf.flashType** + - 首选烧录方法：DFU、UART 或 JTAG + * - **idf.launchMonitorOnDebugSession** + - 在 ESP-IDF 调试会话中启动 ESP-IDF 监视器 + * - **idf.notificationMode** + - ESP-IDF 扩展通知和输出专注模式。（默认全部启用） + * - **idf.showOnboardingOnInit** + - 在激活扩展时显示 ESP-IDF 配置窗口 + * - **idf.saveScope** + - 保存扩展设置的位置 + * - **idf.saveBeforeBuild** + - 在构建之前保存所有编辑的文件（该选项默认启用） + * - **idf.useIDFKconfigStyle** + - 启用 Kconfig 文件的样式验证 + * - **idf.telemetry** + - 启用遥测 + * - **idf.deleteComponentsOnFullClean** + - 在执行 **Full Clean Project** 命令时删除 ``managed_components``（该选项默认禁用） + * - **idf.monitorNoReset** + - 启用 IDF 监视器的不重置标志（该选项默认禁用） + * - **idf.monitorEnableTimestamps** + - 启用 IDF 监视器中的时间戳（该选项默认禁用） + * - **idf.monitorCustomTimestampFormat** + - 在 IDF 监视器中自定义时间戳格式 + * - **idf.monitorStartDelayBeforeDebug** + - 启动 IDF 监视器后延迟开始调试会话 + * - **idf.enableStatusBar** + - 显示或隐藏扩展状态栏项目 + * - **idf.enableSizeTaskAfterBuildTask** + - 在完成 IDF 构建任务后执行 IDF 计算程序大小任务 + * - **idf.customTerminalExecutable** + - 指定要使用的 shell 终端可执行文件的绝对路径（默认使用 VS Code 终端） + * - **idf.customTerminalExecutableArgs** + - idf.customTerminalExecutable 的 shell 参数 + + +自定义构建和烧录任务 +-------------------- + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - 设置 ID + - 描述 + * - **idf.customTask** + - 通过 **ESP-IDF: Execute Custom Task** 命令执行的自定义任务 + * - **idf.preBuildTask** + - 在构建任务之前执行的命令字符串 + * - **idf.postBuildTask** + - 在构建任务之后执行的命令字符串 + * - **idf.preFlashTask** + - 在烧录任务之前执行的命令字符串 + * - **idf.postFlashTask** + - 在烧录任务之后执行的命令字符串 + + +QEMU 相关设置 +------------- + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - 设置 ID + - 描述 + * - **idf.qemuTcpPort** + - QEMU 用于串行通信的 TCP 端口 + + +日志追踪相关设置 +---------------- + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - 设置 + - 描述 + * - **trace.poll_period** + - 设置 apptrace 的 poll_period 参数 + * - **trace.trace_size** + - 设置 apptrace 的 trace_size 参数 + * - **trace.stop_tmo** + - 设置 apptrace 的 stop_tmo 参数 + * - **trace.wait4halt** + - 设置 apptrace 的 wait4halt 参数 + * - **trace.skip_size** + - 设置 apptrace 的 skip_size 参数 + + +其他框架的相关设置 +------------------ + +通过以下设置，可同时使用 ESP-IDF 及其他框架： + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - 设置 ID + - 描述 + * - **idf.espAdfPath** + - 定位 ESP-ADF 框架的路径 (ADF_PATH) + * - **idf.espAdfPathWin** + - 在 Windows 系统中定位 ESP-ADF 框架的路径 (ADF_PATH) + * - **idf.espMdfPath** + - 定位 ESP-MDF 框架的路径 (MDF_PATH) + * - **idf.espMdfPathWin** + - 在 Windows 系统中定位 ESP-MDF 框架的路径 (MDF_PATH) + * - **idf.espMatterPath** + - 定位 ESP-Matter 框架的路径 (ESP_MATTER_PATH) + * - **idf.espRainmakerPath** + - 定位 ESP-Rainmaker 框架的路径 (RMAKER_PATH) + * - **idf.espRainmakerPathWin** + - 在 Windows 系统中定位 ESP-Rainmaker 框架的路径 (RMAKER_PATH) + * - **idf.sbomFilePath** + - 创建 ESP-IDF SBOM 报告的路径 + + +在 ESP-IDF ``settings.json`` 和 ``tasks.json`` 中使用环境变量 +------------------------------------------------------------- + +环境变量 (env) 和其他 ESP-IDF 设置 (config) 可以在 ESP-IDF 设置中通过 ``${env:VARNAME}``（用于环境变量）和 ``${config:ESPIDFSETTING}``（用于设置）进行引用。 + +例如，如果想要使用 ``"~/esp/esp-idf"``，可以将 **idf.espIdfPath** 设为 ``"${env:HOME}/esp/esp-idf"``。