vcpkg Feature Selector
A small VS Code extension for selecting optional vcpkg manifest features used by a CMake-based workspace.
The extension reads the available features directly from the workspace's root vcpkg.json and stores the selected feature set in the CMake Tools cmake.configureArgs setting.
Requirements
The extension requires:
- Visual Studio Code
- the Microsoft CMake Tools extension
- a root
vcpkg.json
- a CMake project that accepts the cache variable
BUILD_VCPKG_FEATURES
The extension does not install or configure vcpkg itself.
Feature Discovery
Available features are read dynamically from the root vcpkg.json.
For example:
{
"features": {
"feature-a": {
"description": "Optional dependencies for feature A",
"dependencies": [
"package-a"
]
},
"feature-b": {
"description": "Optional dependencies for feature B",
"dependencies": [
"package-b"
]
}
}
}
The selector will show the feature names together with their descriptions.
For example:
feature-a Optional dependencies for feature A
feature-b Optional dependencies for feature B
Feature names do not need to be duplicated inside the extension.
If a feature does not define a description, it is still shown normally.
Selecting Features
The selector is available through the package icon in the VS Code status bar or through the VS Code Command Palette:
vcpkg: Select Manifest Features
Multiple features can be selected.
For example:
feature-a
feature-b
is stored as:
-DBUILD_VCPKG_FEATURES=feature-a;feature-b
Feature selections are normalized by:
- removing empty entries
- removing the special
none value
- removing duplicates
- sorting the selected feature names
none
The selector provides a virtual feature called:
none
It means that no optional vcpkg manifest features are selected.
It is stored as:
-DBUILD_VCPKG_FEATURES=none
none is not required to exist as a feature in vcpkg.json.
If none is selected together with real features, none is ignored.
For example:
none
feature-a
results in:
-DBUILD_VCPKG_FEATURES=feature-a
The selected feature set is persisted through:
"cmake.configureArgs": [
"-DBUILD_VCPKG_FEATURES=feature-a"
]
The extension manages only arguments beginning with:
-DBUILD_VCPKG_FEATURES=
Other CMake configure arguments are preserved.
For example:
"cmake.configureArgs": [
"-DSOME_OPTION=ON",
"-DBUILD_VCPKG_FEATURES=none"
]
becomes:
"cmake.configureArgs": [
"-DSOME_OPTION=ON",
"-DBUILD_VCPKG_FEATURES=feature-a"
]
when feature-a is selected.
The workspace CMake configuration is treated as the persistent source of truth for the selected feature set unless the current development environment defines an environment-specific feature selection.
Changes made externally to cmake.configureArgs are detected and reflected in the status bar.
Environment-specific Feature Selection
A development environment can define the feature set that should be active when the extension starts.
This is configured through:
"vcpkgFeatureSelector.environmentFeatures": "feature-a"
For example, a VS Code Dev Container can define:
"customizations": {
"vscode": {
"settings": {
"vcpkgFeatureSelector.environmentFeatures": "feature-a"
}
}
}
Multiple features can be specified using a CMake-style list:
"vcpkgFeatureSelector.environmentFeatures": "feature-a;feature-b"
To explicitly select no optional features, use:
"vcpkgFeatureSelector.environmentFeatures": "none"
Leaving the setting empty means that the environment does not override the persisted feature selection:
"vcpkgFeatureSelector.environmentFeatures": ""
When a non-empty environment feature selection is configured, the extension compares it with the currently persisted CMake feature selection when the extension starts.
If they differ, the extension updates the managed -DBUILD_VCPKG_FEATURES=... entry in cmake.configureArgs and requests a clean CMake configure.
If they are already equal, no configuration change or additional clean configure is requested.
This allows different development environments to establish their intended vcpkg feature set while keeping the interactive feature selector and the normal workspace persistence mechanism.
Because the environment selection is applied when the extension starts, reloading or reopening the VS Code window also restores the feature set declared by the environment.
Changing the selected feature set through the selector triggers:
cmake.cleanConfigure
A clean configure is used because changing the installed vcpkg feature set can otherwise leave stale CMake package information in the existing build directory.
Selecting the already active feature set does nothing and does not trigger another configure.
Cancelling the selector also performs no action.
Changing vcpkg.json itself does not cause this extension to request a clean configure.
CMake Tools or CMake may independently decide to configure after project files change.
Manifest Watching
The extension watches the root:
vcpkg.json
while VS Code is running.
Changes to the manifest automatically refresh:
- available feature names
- feature descriptions
- status information
Restarting the extension is therefore not required after editing feature definitions.
The manifest watcher does not modify the selected CMake feature configuration.
Status Bar
The status bar displays the current feature selection.
When no optional features are selected, it displays the package icon together with:
none
When optional features are selected, it displays the package icon together with the number of selected features.
For example:
📦 2
indicates that two optional features are selected.
The tooltip shows the selected feature names.
Warning State
If a configured feature no longer exists in vcpkg.json, the status bar shows a warning.
The extension does not silently remove the missing feature from the CMake configuration.
The configuration changes only after the user explicitly selects a new feature set.
Error State
The extension shows an error state when it cannot operate correctly, for example when:
- no root
vcpkg.json exists
vcpkg.json cannot be read or parsed- the workspace folder cannot be determined
- CMake Tools is not installed
- more than one root manifest is found in a multi-root workspace
Errors caused directly by a user selection, such as failing to update cmake.configureArgs or failing to invoke the CMake clean-configure command, are also shown as VS Code error notifications.
Multi-root Workspaces
The extension currently supports exactly one root vcpkg.json.
A multi-root workspace is supported only when exactly one workspace folder contains a root manifest.
For example, this is supported:
workspace
├── project/
│ └── vcpkg.json
│
└── documentation/
This is currently not supported:
workspace
├── project-a/
│ └── vcpkg.json
│
└── project-b/
└── vcpkg.json
When multiple root manifests are detected, the extension enters an error state instead of choosing one implicitly.
Command-line Builds
The extension is only a VS Code user interface for selecting the CMake cache value.
It is not required for command-line builds.
The same configuration can be supplied directly to CMake:
cmake --preset <preset-name> \
-DBUILD_VCPKG_FEATURES=feature-a
Multiple features use a CMake list:
cmake --preset <preset-name> \
-DBUILD_VCPKG_FEATURES='feature-a;feature-b'
No optional features can be selected with:
cmake --preset <preset-name> \
-DBUILD_VCPKG_FEATURES=none
When changing feature sets manually from the command line, a fresh configure may be required to avoid stale package information.
Development
The extension is implemented in JavaScript and does not require an npm or TypeScript build step for development.
A typical source layout is:
vcpkg-feature-selector/
├── .vscode/
│ └── launch.json
├── src/
│ └── extension.js
├── package.json
└── README.md
To run the extension during development:
- Open the extension directory in VS Code.
- Press
F5.
- VS Code starts an Extension Development Host.
- Open a CMake workspace containing a root
vcpkg.json.
- The vcpkg feature selector appears in the status bar.
The exact launch configuration can depend on how the extension repository and the test workspace are arranged.
Current Limitations
The following are currently not handled:
- multiple root
vcpkg.json manifests
- dynamic rescanning when workspace folders are added or removed after extension activation
- automatic correction of stale CMake package-cache state caused by manual changes to
vcpkg.json
