From 687243e9f7910bc60ff78f94682e9a44c60d8fd4 Mon Sep 17 00:00:00 2001 From: shenmengjing Date: Thu, 2 Jan 2025 16:25:56 +0800 Subject: [PATCH] docs: Provide CN translation for multiple-projects.rst --- .../additionalfeatures/multiple-projects.rst | 183 +++++++++--------- .../additionalfeatures/multiple-projects.rst | 164 +++++++++++++++- 2 files changed, 259 insertions(+), 88 deletions(-) diff --git a/docs_espressif/en/additionalfeatures/multiple-projects.rst b/docs_espressif/en/additionalfeatures/multiple-projects.rst index 1bccd5590..8dead8011 100644 --- a/docs_espressif/en/additionalfeatures/multiple-projects.rst +++ b/docs_espressif/en/additionalfeatures/multiple-projects.rst @@ -1,99 +1,108 @@ .. _multiple projects: Working with Multiple Projects -================================== +============================== -For big projects, a user will typically have one or more projects to build, flash or monitor. The ESP-IDF Extension follows the `Visual Studio Code Workspace File Schema `_ to identify all projects folders inside the current workspace (which would be the root folder). Please take a look at `Creating User and Workspace Settings `_. +:link_to_translation:`zh_CN:[中文]` -Configuration settings are overriden as: +For big projects, the user often manage multiple projects for building, flashing or monitoring. The ESP-IDF extension follows the `Visual Studio Code Workspace File Schema `_ to identify all project folders inside the current workspace (the root folder). For more details, please refer to `User and Workspace Settings `_. -1. Workspace folder configuration settings in ``${workspaceFolder}/.vscode/settings.json`` -2. Workspace configuration settings defined in the workspace's ``.code-workspace`` file as shown below. -3. User settings defined in +Configuration settings are overridden in the following order: -- **Windows** ``%APPDATA%\Code\User\settings.json`` -- **MacOS** ``$HOME/Library/Application Support/Code/User/settings.json`` -- **Linux** ``$HOME/.config/Code/User/settings.json`` +1. Workspace folder configuration settings in ``${workspaceFolder}/.vscode/settings.json`` +2. Workspace configuration settings in the workspace's ``.code-workspace`` file +3. User settings defined in ``settings.json`` -This extension uses the **idf.saveScope** configuration setting to determine where to save configuration settings in features such as the Setup Wizard. You can modify this using the **ESP-IDF: Select where to Save Configuration Settings** command. + - **Windows**: ``%APPDATA%\Code\User\settings.json`` + - **MacOS**: ``$HOME/Library/Application Support/Code/User/settings.json`` + - **Linux**: ``$HOME/.config/Code/User/settings.json`` -You can select the current project by clicking the **ESP-IDF Current Project** Item in the Visual Studio Code Status bar or by pressing F1 and typing **ESP-IDF: Pick a Workspace Folder** which will determine the folder where to obtain the ESP-IDF Settings such as current device USB port, ESP-IDF path, etc. +This extension uses the ``idf.saveScope`` configuration setting to specify where to save settings for features such as the Setup Wizard. You can modify this using the ``ESP-IDF: Select where to Save Configuration Settings`` command. -Projects folders (Known in vscode as workspace folders) and workspace level settings are defined in some ``.code-workspace`` file such as: +Select the current project by clicking the ``ESP-IDF: Current Project`` icon in the Visual Studio Code status bar or by pressing F1 and typing ``ESP-IDF: Pick a Workspace Folder``. This determines the folder for ESP-IDF settings such as the current device USB port, ESP-IDF path, etc. + +Project folders (known in VS Code as workspace folders) and workspace-level settings are defined in a ``.code-workspace`` file, such as: .. code-block:: JSON - { - "folders": [ - { - "path": "./project1" - }, - { - "path": "./project2" - } - ], - "settings": { - "idf.port": "/dev/ttyUSB1", - "idf.espIdfPath": "${env:HOME}/esp/esp-idf" + { + "folders": [ + { + "path": "./project1" + }, + { + "path": "./project2" + } + ], + "settings": { + "idf.port": "/dev/ttyUSB1", + "idf.espIdfPath": "${env:HOME}/esp/esp-idf" + } } - } -Settings in the root folder's ``.code-workspace`` can be used when your **ESP-IDF Current Project** directory doesn't contain a ``.vscode/settings.json`` file. +Settings in the root folder's ``.code-workspace`` are used when your ``ESP-IDF: Current Project`` directory lacks a ``.vscode/settings.json`` file. + +To open a project with multiple sub-projects in Visual Studio Code, go to ``File`` > ``Open Workspace`` to select the ``.code-workspace`` file describing your workspace. + +You can either manually create this ``.code-workspace`` file and define all sub-folders (sub-projects), or go to ``File`` > ``Save Workspace as`` to save it, which does not automatically add any folder inside the current directory. -If you want to open a project with multiple subprojects in Visual Studio Code, click Menu **File** > **Open Workspace** which will open a window to select the ``.code-workspace`` file describing your workspace. -You can either manually create this ``.code-workspace`` file and define all sub folders (projects) or when you click Menu **File** > **Save Workspace as...** which doesn't automatically add any folder inside the current directory. -You can add a folder to the workspace when you click Menu **File** > **Add Folder to Workspace...**. +Add a folder to the workspace by clicking ``File`` > ``Add Folder to Workspace``. .. note:: - You still need to manually select the corresponding debug configuration in the Debug tab of your current workspace folder. There is a project directory suffix on each debug configuration. + + You must manually select the corresponding debug configuration in the ``Debug`` tab of your current workspace folder. Each debug configuration has a project directory suffix. Example ------------- +------- Consider the following multiple projects directory tree example: .. code-block:: - ---> /my-projects-root - ------> /my-projects-root/project1 - ------> /my-projects-root/project2 - ------------> /my-projects-root/project2/.vscode/settings.json + ---> /my-projects-root + ------> /my-projects-root/project1 + ------> /my-projects-root/project2 + ------------> /my-projects-root/project2/.vscode/settings.json -and ``my-ws.code-workspace``: +And ``my-ws.code-workspace``: .. code-block:: JSON - { - "folders": [ - { - "path": "/my-projects-root/project1" - }, - { - "path": "/my-projects-root/project2" - } - ], - "settings": { - "idf.port": "/dev/ttyUSB1", - "idf.espIdfPath": "${env:HOME}/esp/esp-idf" + { + "folders": [ + { + "path": "/my-projects-root/project1" + }, + { + "path": "/my-projects-root/project2" + } + ], + "settings": { + "idf.port": "/dev/ttyUSB1", + "idf.espIdfPath": "${env:HOME}/esp/esp-idf" + } } - } -1. If you open Visual Studio Code, click Menu **File** > **Open Workspace** and open ``my-ws.code-workspace`` you will see just the folders defined in this workspace (``/my-projects-root/project1`` and ``/my-projects-root/project2``). - - For ``project1``, Visual Studio Code will use the settings from ``my-ws.code-workspace`` first then other required settings from the User Settings. - - For ``project2``, Visual Studio Code will use those settings from ``/my-projects-root/project2/.vscode/settings.json`` first, then all required (and not found) settings from ``my-ws.code-workspace`` and finally in the Visual Studio Code User settings. -2. If you just open the ``/my-projects-root`` or ``/my-projects-root/project1`` directory Visual Studio Code will use the User Settings. - - If you just open the ``/my-projects-root/project2`` directory Visual Studio Code will use the ``/my-projects-root/project2/.vscode/settings.json`` then other required settings from the User Settings. +1. Open Visual Studio Code, go to ``File`` > ``Open Workspace`` and open ``my-ws.code-workspace``, you will see only the folders defined in this workspace (``/my-projects-root/project1`` and ``/my-projects-root/project2``). -.. note:: - If you open ``/my-projects-root``, any of the sub projects will not be recognized as Workspace Folders, you need to add them to ``my-ws.code-workspace`` (manually or using **File** > **Add Folder to Workspace...**) and open this workspace as specified before. + - For ``project1``, Visual Studio Code uses the settings from ``my-ws.code-workspace`` first, then other required settings from the User Settings. + - For ``project2``, Visual Studio Code uses those settings from ``/my-projects-root/project2/.vscode/settings.json`` first, then any missing settings from ``my-ws.code-workspace``, and finally from the User settings. -Use multiple build configuration in the same workspace folder -------------------------------------------------------------------- +2. Open the ``/my-projects-root`` or ``/my-projects-root/project1`` directory, Visual Studio Code uses the User Settings. -Use the `ESP-IDF CMake Multiple Configuration Example `_ to follow this tutorial. + - If you just open the ``/my-projects-root/project2`` directory, Visual Studio Code uses ``/my-projects-root/project2/.vscode/settings.json`` first, then other required settings from the User Settings. -Use the **ESP-IDF: Open Project Configuration** and create two configurations profiles: ``prod1`` and ``prod2`` and ``sdkconfig.prod_common;sdkconfig.prod1`` and ``sdkconfig.prod_common;sdkconfig.prod2`` on the sdkconfig defaults field as shown below: + .. note:: + + If you open ``/my-projects-root``, any of the sub-projects will not be recognized as workspace folders. You need to add them to ``my-ws.code-workspace`` (manually or by clicking ``File`` > ``Add Folder to Workspace``) and open this workspace as specified before. + +Use Multiple Build Configurations in the Same Workspace Folder +-------------------------------------------------------------- + +Use the ESP-IDF CMake `Multiple Build Configurations Example `_ to follow this tutorial. + +Use the ``ESP-IDF: Open Project Configuration`` command to create two configuration profiles: ``prod1`` and ``prod2``. Set ``sdkconfig.prod_common;sdkconfig.prod1`` and ``sdkconfig.prod_common;sdkconfig.prod2`` in the sdkconfig defaults field as shown below: .. image:: ../../../media/tutorials/project_conf/enterConfigName.png @@ -101,54 +110,54 @@ Use the **ESP-IDF: Open Project Configuration** and create two configurations pr .. image:: ../../../media/tutorials/project_conf/prod2.png -After creating each profile and the configuration settings for each profile, click the ``Save`` button and use the **ESP-IDF: Select Project Configuration** command to choose the configuration to override extension configuration settings. +After creating each profile and setting the configuration, click the ``Save`` button. Use the ``ESP-IDF: Select Project Configuration`` command to choose the configuration to override extension configuration settings. .. image:: ../../../media/tutorials/project_conf/selectConfig.png -After a configuration profile is selected, the selected profile will be shown in the status bar as shown before. +Once a configuration profile is selected, it will appear in the status bar as shown before. .. image:: ../../../media/tutorials/project_conf/configInStatusBar.png -Now use the **ESP-IDF: Build your Project** to build the project for ``prod1`` and ``prod2``. You can observe binaries generated for each profiles in the path defined in each profile as before. You can use **ESP-IDF: Select Project Configuration** command to switch between configurations. +Now, use the ``ESP-IDF: Build your Project`` command to build the project for ``prod1`` and ``prod2``. You will see binaries generated for each profile in the specified path. Use the ``ESP-IDF: Select Project Configuration`` command to switch between configurations. -Use the **ESP-IDF: Open Project Configuration** command to modify, add or delete the configuration profiles. If you want to stop using these profile, just delete all configuration profiles. +Use the ``ESP-IDF: Open Project Configuration`` command to modify, add, or delete the configuration profiles. To stop using these profiles, delete all configuration profiles. Multiple ESP-IDF Versions --------------------------------- +------------------------- -You can use multiple ESP-IDF versions, one for each ESP-IDF project by explicitly defining your configuration settings in your current project directory ``.vscode/settings.json``. +You can use multiple ESP-IDF versions, one for each project, by explicitly defining your configuration settings in the ``.vscode/settings.json`` file of your current project directory. -1. Set the ``idf.saveScope`` to WorkspaceFolder with the **ESP-IDF: Select where to Save Configuration Settings** command or directly in the ``.vscode/settings.json`` of desired project opened in Visual Studio Code. +1. Set ``idf.saveScope`` to workspace folder using the ``ESP-IDF: Select where to Save Configuration Settings`` command, or by directly editing the ``.vscode/settings.json`` file of the desired project in Visual Studio Code. -2. Configure the extension as described in :ref:`Install ESP-IDF and Tools ` documentation. +2. Configure the extension as described in :ref:`Install ESP-IDF and Tools `. -3. Make sure to delete any previous build directory since a different ESP-IDF version would not work if there is any cache of previous build. +3. Delete any previous build directory, as an different ESP-IDF version will not work if there is any cache of previous build. -4. Repeat from 1) on any project you would like to use a different version from the global user settings. +4. Repeat from step 1 for any project where you want to use an ESP-IDF version different from the global user settings. -Using Multiple Build Configuration Manually ------------------------------------------------- +Using Multiple Build Configurations Manually +-------------------------------------------- -As shown in the `ESP-IDF CMake Multiple Configuration example `_ you can use multiple build directories and multiple sdkconfig defaults files to produce different production output. +As shown in the ESP-IDF CMake `Multiple Build Configurations Example `_, you can use multiple build directories and multiple sdkconfig defaults files to produce different production outputs. -In this extension you can define the build directory with the ``idf.buildPath`` (``idf.buildPathWin`` fo Windows) configuration setting and the list of sdkconfig default files with ``idf.sdkconfigDefaults`` configuration. The value of these settings will be using by the extension build command. +In this extension, you can define the build directory with the ``idf.buildPath`` (``idf.buildPathWin`` for Windows) configuration setting, and define the list of sdkconfig defaults files with ``idf.sdkconfigDefaults``. These settings will be used by the extension build command. -Say you want to make product 1: +For example, to create product 1: -1. you have sdkconfig files ``sdkconfig.prod_common`` and ``sdkconfig.prod1`` and you want the resulting firmware to be generated in ``/build_prod1`` where ``build_prod1`` is the name of the custom build folder. -2. Add these settings in ``/.vscode/settings.json``: +1. Create sdkconfig files ``sdkconfig.prod_common`` and ``sdkconfig.prod1``, and the resulting firmware will be generated in ``/build_prod1``, where ``build_prod1`` is the custom build folder name. +2. In your project’s ``.vscode/settings.json`` file, add the following settings: -.. code-block:: JSON + .. code-block:: JSON - { - // ... - "idf.buildPath": "${workspaceFolder}/build_prod1", - "idf.sdkconfigDefaults": ["sdkconfig.prod_common", "sdkconfig.prod1"] - // ... - } + { + // ... + "idf.buildPath": "${workspaceFolder}/build_prod1", + "idf.sdkconfigDefaults": ["sdkconfig.prod_common", "sdkconfig.prod1"] + // ... + } -3. Build your project using the **ESP-IDF: Build your Project** command. +3. Build your project using the ``ESP-IDF: Build your Project`` command. -4. Your resulting files will be generated in ``/build_prod1`` and the sdkconfig being used by the SDK Configuration Editor will be ``/build_prod1/sdkconfig``. +4. The resulting files will be generated in ``/build_prod1``, and the sdkconfig used by the SDK Configuration Editor will be ``/build_prod1/sdkconfig``. -5. Change values in 2) for different products and configurations. +5. Change the values in step 2 for different products and configurations accordingly. diff --git a/docs_espressif/zh_CN/additionalfeatures/multiple-projects.rst b/docs_espressif/zh_CN/additionalfeatures/multiple-projects.rst index ff0f4cbe3..cdd956576 100644 --- a/docs_espressif/zh_CN/additionalfeatures/multiple-projects.rst +++ b/docs_espressif/zh_CN/additionalfeatures/multiple-projects.rst @@ -1 +1,163 @@ -.. include:: ../../en/additionalfeatures/multiple-projects.rst +.. _multiple projects: + +处理多个项目 +============ + +:link_to_translation:`en:[English]` + +对于大型项目,通常需要构建、烧录或监视多个项目。ESP-IDF 扩展遵循 `VS Code 工作区文件架构 `_ 来识别当前工作区(即根目录)下的所有项目文件夹。详情请参阅 `用户和工作区设置 `_。 + +配置将按照如下优先级进行覆盖: + +1. 工作区文件夹中 ``${workspaceFolder}/.vscode/settings.json`` 文件里定义的设置 +2. 工作区中 ``.code-workspace`` 文件里定义的配置 +3. ``settings.json`` 文件中定义的用户设置 + + - **Windows**:``%APPDATA%\Code\User\settings.json`` + - **MacOS**:``$HOME/Library/Application Support/Code/User/settings.json`` + - **Linux**:``$HOME/.config/Code/User/settings.json`` + +此扩展使用 ``idf.saveScope`` 配置选项来确定在某些功能(如设置向导)中,配置设置应该保存到哪里。若想改变位置,可以使用 ``ESP-IDF:选择配置存储位置`` 命令进行修改。 + +点击 VS Code 状态栏中的 ``ESP-IDF:当前项目`` 图标或按 F1 唤醒命令面板,输入 ``ESP-IDF:选择工作区文件夹`` 来选择当前项目,确定 ESP-IDF 设置(如当前设备的 USB 端口、ESP-IDF 路径等)将应用于哪个文件夹。 + +``.code-workspace`` 文件定义了项目文件夹(即 VS Code 中的工作区文件夹)和工作区级别的设置,如下所示: + +.. code-block:: JSON + + { + "folders": [ + { + "path": "./project1" + }, + { + "path": "./project2" + } + ], + "settings": { + "idf.port": "/dev/ttyUSB1", + "idf.espIdfPath": "${env:HOME}/esp/esp-idf" + } + } + +若 ``ESP-IDF:当前项目`` 目录中不包含 ``.vscode/settings.json`` 文件,则使用根目录下 ``.code-workspace`` 中的设置。 + +若想在 VS Code 中打开一个包含多个子项目的项目,请前往菜单栏中的 ``文件`` > ``打开工作区``,选择描述你工作区的 ``.code-workspace`` 文件。 + +你可以手动创建 ``.code-workspace`` 文件并定义所有子文件夹(子项目),也可以点击菜单栏中的 ``文件`` > ``将工作区另存为`` 来保存当前的工作区,但要注意后者不会自动包含当前目录下的任何文件夹。 + +前往菜单栏中的 ``文件`` > ``将文件夹添加到工作区``,可以将文件夹添加到工作区。 + +.. note:: + + 必须在当前工作区文件夹的 ``调试`` 选项卡中手动选择相应的调试配置。每个调试配置都有一个项目目录后缀。 + +示例 +---- + +请参考以下多项目目录树示例: + +.. code-block:: + + ---> /my-projects-root + ------> /my-projects-root/project1 + ------> /my-projects-root/project2 + ------------> /my-projects-root/project2/.vscode/settings.json + + +以及 ``my-ws.code-workspace``: + +.. code-block:: JSON + + { + "folders": [ + { + "path": "/my-projects-root/project1" + }, + { + "path": "/my-projects-root/project2" + } + ], + "settings": { + "idf.port": "/dev/ttyUSB1", + "idf.espIdfPath": "${env:HOME}/esp/esp-idf" + } + } + +1. 打开 VS Code,前往菜单栏中的 ``文件`` > ``打开工作区`` 并打开 ``my-ws.code-workspace``,你只能看到在当前工作区中定义的文件夹(``/my-projects-root/project1`` 和 ``/my-projects-root/project2``)。 + + - 对于 ``project1``,VS Code 优先使用 ``my-ws.code-workspace`` 中的设置,然后再从用户设置中获取其他所需的设置。 + - 对于 ``project2``,VS Code 优先使用 ``/my-projects-root/project2/.vscode/settings.json`` 中的设置,其次从 ``my-ws.code-workspace`` 中获取缺失的设置,最后从用户设置中获取其余设置。 + +2. 打开 ``/my-projects-root`` 或 ``/my-projects-root/project1`` 目录,VS Code 将使用用户设置。 + + - 如果只打开 ``/my-projects-root/project2`` 目录,VS Code 将首先使用 ``/my-projects-root/project2/.vscode/settings.json`` 中定义的设置,然后使用用户设置中定义的其他必要设置。 + + .. note:: + + 若打开 ``/my-projects-root``,任何子项目都不会被识别为工作区文件夹。你需要将这些项目添加到 ``my-ws.code-workspace`` (手动添加或点击菜单栏中的 ``文件`` > ``将文件夹添加到工作区``),并按照之前指定的方式打开此工作区。 + +在同一工作区文件夹中使用多种构建配置 +------------------------------------ + +本章教程使用了 ESP-IDF CMake `多种构建配置示例 `_。 + +使用 ``ESP-IDF:打开项目配置`` 命令并创建两个配置文件:``prod1`` 和 ``prod2``。如下所示,在 sdkconfig defaults 字段中设置 ``sdkconfig.prod_common;sdkconfig.prod1`` 和 ``sdkconfig.prod_common;sdkconfig.prod2``: + +.. image:: ../../../media/tutorials/project_conf/enterConfigName.png + +.. image:: ../../../media/tutorials/project_conf/prod1.png + +.. image:: ../../../media/tutorials/project_conf/prod2.png + +创建好配置文件并为每个文件都设置好配置项后,点击 ``保存`` 按钮。使用 ``ESP-IDF:选择项目配置`` 命令来选择要覆盖的扩展配置。 + +.. image:: ../../../media/tutorials/project_conf/selectConfig.png + +选定配置文件后,所选文件将显示在 VS Code 状态栏中。 + +.. image:: ../../../media/tutorials/project_conf/configInStatusBar.png + +使用 ``ESP-IDF:构建项目`` 命令,为配置文件 ``prod1`` 和 ``prod2`` 构建项目。指定路径中将出现每个配置文件生成的二进制文件。使用 ``ESP-IDF:选择项目配置`` 命令,可以切换不同的构建配置。 + +使用 ``ESP-IDF:打开项目配置`` 命令,可以修改、添加或删除配置文件。如果不再需要这些配置文件,删除即可。 + +多个 ESP-IDF 版本 +----------------- + +在 VS Code 中可以使用多个 ESP-IDF 版本,每个项目配置一个不同的版本。只要在当前项目目录下的 ``.vscode/settings.json`` 文件中显式定义项目配置。 + +1. 使用 ``ESP-IDF:选择配置存储位置`` 命令或在 VS Code 中打开所需项目的 ``.vscode/settings.json`` 文件进行编辑,将 ``idf.saveScope`` 设置为工作区文件夹级别。 + +2. 参照 :ref:`安装 ESP-IDF 和工具 `,配置扩展。 + +3. 删除先前的构建目录。若存在先前构建的缓存,则不同的 ESP-IDF 版本将无法工作。 + +4. 如果你希望使用与全局用户设置版本不同的 ESP-IDF,请在所需项目中重复步骤 1。 + +手动使用多种构建配置 +-------------------- + +如 ESP-IDF CMake `多种构建配置示例 `_ 所示,可以使用多个构建目录和多个 sdkconfig 默认文件来生成不同版本的最终产品。 + +在此扩展中,可以使用 ``idf.buildPath`` (Windows 系统中使用 ``idf.buildPathWin``)来定义构建目录,并使用 ``idf.sdkconfigDefaults`` 来定义 sdkconfig 默认文件列表。扩展构建命令会使用这些定义好的配置。 + +例如,如果要制作产品 1: + +1. 创建 sdkconfig 文件 ``sdkconfig.prod_common`` 和 ``sdkconfig.prod1``,之后 ``/build_prod1`` (``build_prod1`` 是自定义构建文件夹的名称)中将生成固件。 +2. 在当前项目的 ``.vscode/settings.json`` 文件中添加下列设置: + + .. code-block:: JSON + + { + // ... + "idf.buildPath": "${workspaceFolder}/build_prod1", + "idf.sdkconfigDefaults": ["sdkconfig.prod_common", "sdkconfig.prod1"] + // ... + } + +3. 使用 ``ESP-IDF:构建项目`` 命令构建你的项目。 + +4. ``/build_prod1`` 中将生成固件文件,而 SDK 配置编辑器使用的 sdkconfig 文件位于 ``/build_prod1/sdkconfig``。 + +5. 对于不同的产品和配置,请在步骤 2 中更改相应的值。