Project Configuration Editor

[中文]

The extension has multiple settings to configure the ESP-IDF project. To allow multiple configuration settings for the same project, you can use the Project Configuration Editor to define multiple profiles with different settings for each profile. The table of contents is as follows:

Configuring the Extension for One Build Configuration

A typical ESP-IDF Project Structure is as follows:

- /path/to/esp-project/
            - CMakeLists.txt
            - sdkconfig
            - components/ - component1/ - CMakeLists.txt
                                        - Kconfig
                                        - src1.c
                          - component2/ - CMakeLists.txt
                                        - Kconfig
                                        - src1.c
                                        - include/ - component2.h
            - main/       - CMakeLists.txt
                          - src1.c
                          - src2.c

            - build/

In the ESP-IDF CMake build system, the project configuration settings are saved using the SDK Configuration Editor, which stores these values in a /path/to/esp-project/sdkconfig file. By default, this file is created in the ESP-IDF project root directory, and a /path/to/esp-project/build directory is used as the build directory path.

When the current ESP-IDF project is under version control, the /path/to/esp-project/sdkconfig can change with any user build, potentially altering the project’s expected behavior. To prevent this, it is better to move project-specific settings to a sdkconfig.defaults file (or list of files) that is not modified by the build system. /path/to/esp-project/sdkconfig can be added to the .gitignore list. The sdkconfig.defaults can be generated by the ESP-IDF: Save Default SDKCONFIG file (save-defconfig) command available in ESP-IDF v5.0 or higher.

Note

The sdkconfig.defaults file is used by the build system to override defaults project settings when creating the sdkconfig file, as described in the ESP-IDF documentation Custom Sdkconfig Defaults.

With this extension’s settings, the default build path (/path/to/esp-project/build), sdkconfig file path, and sdkconfig.defaults can be modified from their default location.

In this extension, you can define the build directory with the idf.buildPath (idf.buildPathWin for Windows) configuration setting and the list of sdkconfig default files with idf.sdkconfigDefaults configuration. These values will be used by the extension build command.

For example, to create product 1:

1. You have sdkconfig files sdkconfig.prod_common and sdkconfig.prod1 and want the resulting firmware to be generated in <your-project>/build_prod1, where build_prod1 is the name of the custom build folder.

2. Add these settings in <your-project>/.vscode/settings.json:

   {
   // ...
   "idf.buildPath": "${workspaceFolder}/build_prod1",
   "idf.sdkconfigDefaults": ["sdkconfig.prod_common", "sdkconfig.prod1"]
   // ...
   }
   

3. Build your project using the ESP-IDF: Build your Project command.

4. Your resulting files will be generated in <your-project>/build_prod1, and the sdkconfig used by the SDK Configuration Editor will be <your-project>/build_prod1/sdkconfig.

   Note

   The ESP-IDF CMake Multiple configuration example defines the sdkconfig location in the CMakeLists.txt file, which will make idf.sdkconfigFilePath NOT work.

5. Change values in step 2 for different products and configurations.

With the ESP-IDF: SDK Configuration Editor, you can specify the build directory with Build Directory Path, the location of the SDKConfig file with SDKConfig File Path, and the default configuration files with SDKConfig Defaults to generate the SDKConfig file in the specified path.

Configuring the Extension for Multiple Build Configurations

1. Go to menu View > Command Palette.

2. Type ESP-IDF: Open Project Configuration and select the command.

3. This launches a project configuration wizard to manage the project configuration profiles, recording the following settings for each configuration:

   Setting ID	Description
   idf.cmakeCompilerArgs	Arguments for CMake compilation task
   idf.ninjaArgs	Arguments for Ninja build task
   idf.buildPath	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.customExtraVars	Variables to be added to system environment variables, IDF_TARGET is set here
   idf.flashBaudRate	Flash baud rate
   idf.monitorBaudRate	Monitor baud rate (empty by default to use SDKConfig CONFIG_ESP_CONSOLE_UART_BAUDRATE)
   idf.openOcdDebugLevel	Set OpenOCD debug Level (0-4) Default: 2
   idf.openOcdConfigs	Configuration files for OpenOCD, relative to OPENOCD_SCRIPTS folder
   idf.openOcdLaunchArgs	Launch arguments for OpenOCD, default is []. If defined, idf.openOcdConfigs and idf.openOcdDebugLevel are ignored
   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

4. After defining a profile and the settings for each profile:

   • Go to menu View > Command Palette

   • Type ESP-IDF: Select Project Configuration command to choose the configuration to override extension configuration settings.

Multiple configuration profiles allow you to store settings together and easily switch between them.

Project Configuration Profiles

The project configuration file is a JSON file that contains the configuration settings for the extension. The file is created when you use the ESP-IDF: Open Project Configuration command, and is saved in the root directory of your ESP-IDF project.

The file is a JSON object with a list of profiles. Each profile is a JSON object with the following properties:

{
  "profile1": {
     // profile1 settings
  },
  "profile2": {
     // profile2 settings
  }
}

The profile name is the key of the JSON object, and the value is a JSON object with the configuration settings for that profile. The profile name can be any string, but it is recommended to use a descriptive name that reflects the purpose of the profile.

The profile name is used to identify the profile when using the ESP-IDF: Select Project Configuration command. The profile name is also used to display the current profile in the status bar.

The profile name is not case-sensitive, so prod1 and Prod1 are considered the same profile.

The profile settings are stored in a JSON object with the following properties. Notice that arrays are expected to have string elements:

{
  "profileName": {
     "build": {
        "compileArgs": [],
        "ninjaArgs": [],
        "buildDirectoryPath": "",
        "sdkconfigDefaults": [],
        "sdkconfigFilePath": ""
     },
     "env": {},
     "idfTarget": "",
     "flashBaudRate": "",
     "monitorBaudRate": "",
     "openOCD": {
        "debugLevel": 0,
        "configs": [],
        "args": []
     },
     "tasks": {
        "preBuild": "",
        "preFlash": "",
        "postBuild": "",
        "postFlash": ""
     }
  }
}

While each field is self-explanatory, here is the mapping of the profile settings to the extension settings:

Setting ID Replaced	Field in Profile that Overrides This Setting
idf.cmakeCompilerArgs	[“profileName”].build.compileArgs
idf.ninjaArgs	[“profileName”].build.ninjaArgs
idf.buildPath	[“profileName”].build.buildDirectoryPath
idf.sdkconfigFilePath	[“profileName”].build.sdkconfigFilePath
idf.sdkconfigDefaults	[“profileName”].build.sdkconfigDefaults
idf.customExtraVars	[“profileName”].env and [“profileName”].idfTarget will replace idf.customExtraVars[“IDF_TARGET”]
idf.flashBaudRate	[“profileName”].flashBaudRate
idf.monitorBaudRate	[“profileName”].monitorBaudRate
idf.openOcdDebugLevel	[“profileName”].openOCD.debugLevel
idf.openOcdConfigs	[“profileName”].openOCD.configs
idf.openOcdLaunchArgs	[“profileName”].openOCD.args
idf.preBuildTask	[“profileName”].tasks.preBuild
idf.postBuildTask	[“profileName”].tasks.postBuild
idf.preFlashTask	[“profileName”].tasks.preFlash
idf.postFlashTask	[“profileName”].tasks.postFlash

Multiple Configuration Tutorial

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:

In each profile, type sdkconfig.prod_common in the sdkconfig defaults field and press + to add another sdkconfig file. Type sdkconfig.prod1 for the prod1 profile and sdkconfig.prod2 for the prod2 profile.

After creating each profile and configuring the settings, click the Save button at the top. Use the ESP-IDF: Select Project Configuration command to choose the configuration to override extension settings.

Once a configuration profile is selected, it will appear in the status bar.

Use the ESP-IDF: Build your Project command to build the project for the selected profile (either prod1 or prod2). Binaries for each profile are generated in the path defined in each profile. 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 configuration profiles. To stop using these profiles, delete all configuration profiles.

These profiles and their settings are saved in /path/to/esp-project/esp_idf_project_configuration.json.

Development and Release Profiles for ESP-IDF Project

For this example we will create two profiles, development and production, to define separate build directories and sdkconfig files.

1. Go to View > Command Palette.

2. Type ESP-IDF: Save Default SDKCONFIG file (save-defconfig) and select the command to generate a sdkconfig.defaults file. This command is available in ESP-IDF v5.0 or higher. You can also create this sdkconfig.defaults file manually.

3. Go to View > Command Palette.

4. Type ESP-IDF: Open Project Configuration and select the command to create a new profile named production. Set SDKConfig Defaults to the existing sdkconfig.defaults file. If you want to separate the build directory for this new production profile from the default /path/to/esp-project/build directory, specify a custom path in the Build Directory Path field (e.g., /path/to/esp-project/build_production). Similarly, set the SDKConfig File Path field to a custom location (e.g., /path/to/esp-project/build_production/sdkconfig).

5. Create a new profile named development. To keep development and production files separate, set Build Directory Path to a custom location (e.g., /path/to/esp-project/build_dev) and SDKConfig File Path to /path/to/esp-project/build_dev/sdkconfig.

6. After creating each profile and configuring the settings, click the Save button. Use the ESP-IDF: Select Project Configuration command to choose the desired profile.

7. When you choose the production profile and use the ESP-IDF: Build your Project command, the /path/to/esp-project/build_production/sdkconfig file will be created, and the binaries will be generated in /path/to/esp-project/build_production.

8. If you choose the development profile, the /path/to/esp-project/build_dev/sdkconfig file will be created, and the binaries will be generated in /path/to/esp-project/build_dev.

9. These profiles and their settings will be saved in the /path/to/esp-project/esp_idf_project_configuration.json.

The previous production profile can be divided into multiple production profiles, as demonstrated in the ESP-IDF CMake multi_config example and Multiple Configuration Tutorial. This is achieved by splitting the sdkconfig.defaults file into a common settings file (sdkconfig.prod_common) and product-specific settings files (sdkconfig.prod1 and sdkconfig.prod2). In the Project Configuration Editor, you can specify multiple SDKConfig Defaults files using a semicolon-separated format (e.g., sdkconfig.prod_common;sdkconfig.prod1), and these files will be loaded in order as explained here.

This is just one example of what the Project Configuration Editor can do. You can also define multiple profiles for other development scenarios, such as testing, profiling, and more.