External Project Support

The extension supports an external project development mode, in which the Ameba SDK and the application project directory are separate. Compared with the SDK Root project mode, where you develop directly inside the SDK directory, it has the following advantages:

  • One SDK can be shared among multiple projects, so there is no need to download it again for every project.

  • Application code is separated from SDK code, which makes independent version management easier.

  • When switching the SDK version, you only need to change the configuration file, without reorganizing the project directory.

Comparison of the two project modes:

Scenario

SDK Root project

External project

Directory opened in VS Code

The SDK root directory or one of its subdirectories

A standalone application project directory

SDK path source

Detected automatically by the extension

Configured in .vscode/settings.json

Example selection

Supported

Not supported (the example dropdown is not shown)

Build / Flash / Monitor

Run in the SDK directory

Run in the external project root directory

New External Project

Use the wizard to quickly create a new external project with a complete .vscode configuration.

How to open: Command panel Advanced → New External Project

Wizard steps:

  1. SDK selection — Choose from the list of known SDK paths (with version information and source labels), or click Browse… to specify one manually. After you select a valid SDK with Browse, the path is recorded automatically for next time.

  2. Template selection — Choose a project template from the SDK examples directory, grouped by category, or choose Blank Project. The README.md of the selected template is previewed on the right in real time.

  3. Chip selection — Select the target chip model.

  4. Project path & name — Choose the directory in which to save the project and enter the project name (when a specific template is selected, the template name is filled in automatically and can be changed freely).

  5. Confirm & create — Check the SDK / Template / Chip / Project path summary and click Create Project to create the project.

  6. Done — Shows the project path and provides an Open in New Window button.

After creation, .vscode/settings.json and .vscode/c_cpp_properties.json are generated automatically in the project root directory. They contain the SDK path, target chip, build output path, code navigation configuration and so on. See Code Navigation.

Import Existing External Project

Import an existing Ameba external project into the extension, generating or completing the .vscode configuration files automatically.

Trigger A (import by command):

  1. Command panel Advanced → Import External Project, or press Ctrl+Shift+P and enter Ameba: Import External Project.

  2. In the folder picker that appears, select the project root directory. If you select an SDK root directory, the extension shows a notice and stops.

  3. If the project has no .vscode configuration, the extension guides you to select the SDK path and target chip, and generates the configuration files automatically.

  4. After the configuration is complete, you can choose to open the project in the current window or in a new window.

Trigger B (open a folder):

  1. Open the external project directory through File → Open Folder.

  2. If the project has no .vscode configuration or the SDK path is invalid, the status bar shows ⚠ Not Ready and the SDK environment not ready. notice appears in the panel.

  3. Click the Setup Wizard button next to the notice and select an SDK through the Setup Wizard (download one or use an existing local SDK). After the wizard finishes, the extension generates the .vscode configuration automatically and points it to that SDK.

  4. The wizard does not prompt for a chip. It reuses the currently selected chip by default, or the first chip in the SDK if none is selected; you can select a different one in the status bar.

To specify the SDK path and target chip manually, use Set Root SDK Path.

Set Root SDK Path

Select the SDK path and target chip for a manually opened external project, generating or updating .vscode/settings.json and .vscode/c_cpp_properties.json. It can also be used to switch the SDK version used by an external project.

How to open: Command panel Advanced → Set Root SDK Path, or press Ctrl+Shift+P and enter Ameba: Set Root SDK Path.

The wizard shows selection lists for the SDK path and the target chip in turn. The SDK list contains all known SDKs (with version numbers and source labels), and you can also click Browse… to specify a new path. If .vscode/settings.json already exists, a confirmation dialog appears; after you confirm, only the ameba.* and clangd.* fields are updated and all other settings stay unchanged. The generated settings.json contains the following key settings:

{
  "ameba.rootSDKPath": "<path to the ameba-rtos SDK root directory>",
  "ameba.projectPath": "<path to the current project root directory>",
  "ameba.targetChip": "<target chip model, such as RTL8720E>",
  "ameba.buildPath": "build_<chip model>/build"
}

After a valid SDK is selected, ameba.rootSDKPath is updated automatically and the extension re-detects the development environment.

Note

When this command is run in an SDK Root project, the SDK selection list is not shown. The extension uses the current workspace as the SDK directly and only generates the .vscode configuration.