AGENT SKILL

presets-vs-kits

Use when writing or reviewing code that must work in both CMake Presets and Kits/Variants modes. Covers configure, build, test, environment, and generator paths. Triggers: "presets vs kits", "useCMakePresets", "works in both modes".

使用场景测试与质量
License 许可
MIT
最近更新
2026-11-11
Stars
★ 1.7k
Forks
559

01 前言 Front Matter

name
presets-vs-kits
description
Use when writing or reviewing code that must work in both CMake Presets and Kits/Variants modes. Covers configure, build, test, environment, and generator paths. Triggers: "presets vs kits", "useCMakePresets", "works in both modes".

03 SKILL.md 正文

Presets Mode vs Kits/Variants Mode

Guide for writing code that works correctly in both operating modes of CMake Tools. Any shared code path (configure, build, test, environment, targets) must handle both modes.


The two modes

CMake Tools operates in one of two mutually exclusive modes per project folder:

Presets mode Kits/variants mode
Source of truth CMakePresets.json / CMakeUserPresets.json Kit selection + variant settings
When active cmake.useCMakePresets is 'always', or 'auto' and preset files exist cmake.useCMakePresets is 'never', or 'auto' and no preset files exist
Runtime check CMakeProject.useCMakePresets === true CMakeProject.useCMakePresets === false

How the mode is determined

// src/config.ts
export type UseCMakePresets = 'always' | 'never' | 'auto';

// src/cmakeProject.ts — doUseCMakePresetsChange()
const usingCMakePresets =
    useCMakePresets === 'always' ? true :
    useCMakePresets === 'never'  ? false :
    await this.hasPresetsFiles();          // 'auto' — check for CMakePresets.json

The resolved boolean is stored in CMakeProject._useCMakePresets and exposed via the useCMakePresets getter.


When you MUST handle both modes

Any shared code path that touches configure, build, test, environment setup, or target resolution must branch on the mode. Omitting the check for one mode is a latent bug.

The canonical branching pattern

// From src/cmakeProject.ts — configure validation (real code)
if (!this.useCMakePresets) {
    // Kits mode: require a kit and variant
    if (!this.activeKit) {
        await vscode.window.showErrorMessage(
            localize('cannot.configure.no.kit', 'Cannot configure: No kit is active for this CMake project')
        );
        return { exitCode: -1, resultType: ConfigureResultType.Other };
    }
    if (!this.variantManager.haveVariant) {
        await this.variantManager.selectVariant();
    }
} else if (!this.configurePreset) {
    // Presets mode: require a configure preset
    void vscode.window.showErrorMessage(
        localize('cannot.configure.no.config.preset', 'Cannot configure: No configure preset is active')
    );
    return { exitCode: -1, resultType: ConfigureResultType.Other };
}

Another real example — default build targets

// src/cmakeProject.ts — getDefaultBuildTargets()
if (this.useCMakePresets && (!defaultTarget || defaultTarget === this.targetsInPresetName)) {
    targets = this.buildPreset?.targets;
}
if (!this.useCMakePresets && !defaultTarget) {
    targets = await this.allTargetName;
}

Canonical data access — Presets mode

Merged preset tree

Use PresetsController (in src/presets/presetsController.ts) to access the merged, expanded preset tree. Never re-parse CMakePresets.json or CMakeUserPresets.json directly — the controller handles include chaining, expansion, and file watching.

Active presets on CMakeProject

CMakeProject.configurePreset   // ConfigurePreset | null
CMakeProject.buildPreset       // BuildPreset | null
CMakeProject.testPreset        // TestPreset | null
CMakeProject.packagePreset     // PackagePreset | null
CMakeProject.workflowPreset    // WorkflowPreset | null

Preset types

All preset interfaces are defined in src/presets/preset.ts. Key types include ConfigurePreset, BuildPreset, TestPreset, PackagePreset, WorkflowPreset.

CMake executable override

In presets mode, the configure preset can override the CMake path:

// src/cmakeProject.ts
const overWriteCMakePathSetting = this.useCMakePresets
    ? this.configurePreset?.cmakeExecutable
    : undefined;

Canonical data access — Kits/variants mode

Active kit

CMakeProject.activeKit   // Kit | null — from src/kits/kit.ts

Kit environment

import { effectiveKitEnvironment } from '@cmt/kits/kit';

// Used in src/drivers/cmakeDriver.ts:
this._kitEnvironmentVariables = await effectiveKitEnvironment(kit, this.expansionOptions);

This merges compiler paths, VS Developer Environment (on Windows via vcvarsall.bat), and any custom environmentVariables defined on the kit.

SpecialKits — always check before treating a kit as a real compiler

// src/kits/kit.ts
export enum SpecialKits {
    ScanForKits = '__scanforkits__',
    Unspecified = '__unspec__',
    ScanSpecificDir = '__scan_specific_dir__',
}

These sentinel values appear in the kit list as UI actions. Before using kit.compilers, kit.toolchainFile, or kit.preferredGenerator, check:

if (kit.name === SpecialKits.Unspecified || kit.name === SpecialKits.ScanForKits) {
    // Not a real kit — skip compiler logic
}

Kit interface

// src/kits/kit.ts (key fields)
export interface Kit extends KitDetect {
    name: string;
    description?: string;
    preferredGenerator?: CMakeGenerator;
    cmakeSettings?: Record<string, string | string[]>;
    compilers?: Record<string, string>;
    toolchainFile?: string;
    environmentVariables?: Record<string, string>;
    environmentSetupScript?: string;
    visualStudio?: string;
    visualStudioArchitecture?: string;
}

Variant handling

Variants (src/kits/variant.ts) provide build type and other CMake variable overrides in kits mode. The VariantManager is only initialized when not using presets:

// src/cmakeProject.ts
if (!this.useCMakePresets) {
    await this.variantManager.initialize(this.folderName);
    await drv.setVariant(this.variantManager.activeVariantOptions, ...);
}

Generator handling in both modes

Multi-config vs single-config

Always check the generator before any build-type logic:

import { isMultiConfGeneratorFast } from '@cmt/util';

// src/util.ts
export function isMultiConfGeneratorFast(gen?: string): boolean {
    return gen !== undefined
        && (gen.includes('Visual Studio') || gen.includes('Xcode') || gen.includes('Multi-Config'));
}
Generator type Examples Build type mechanism
Single-config Ninja, Unix Makefiles CMAKE_BUILD_TYPE set at configure time
Multi-config Visual Studio, Xcode, Ninja Multi-Config --config <type> passed at build time

Exception: cmake.setBuildTypeOnMultiConfig

When this setting is true, CMAKE_BUILD_TYPE is also set at configure time for multi-config generators (used by some CMake scripts that read it). See src/drivers/cmakeDriver.ts.

How it shows up in both modes

  • Presets mode: The generator is embedded in configurePreset.generator. The preset may also set CMAKE_BUILD_TYPE in cacheVariables or use configuration in the build preset.
  • Kits mode: The generator comes from Kit.preferredGenerator.name or is auto-detected. Build type comes from the active variant.

Common mistakes

1. Testing only one mode

If you add or change behavior in a shared code path, you must verify it works in both presets mode and kits/variants mode. Many bugs ship because the developer only tested with presets (or only with kits).

2. Assuming single-config generator

Never assume CMAKE_BUILD_TYPE is the way to set the build configuration. Always check isMultiConfGeneratorFast() first.

// ❌ Wrong — breaks with Visual Studio / Ninja Multi-Config
args.push(`-DCMAKE_BUILD_TYPE=${buildType}`);

// ✅ Correct
if (!isMultiConfGeneratorFast(generator)) {
    args.push(`-DCMAKE_BUILD_TYPE=${buildType}`);
}

3. Reading preset files directly

// ❌ Wrong — bypasses include chaining, expansion, and caching
const presets = JSON.parse(fs.readFileSync('CMakePresets.json', 'utf8'));

// ✅ Correct — use the PresetsController
const configPreset = this.configurePreset;

4. Not checking for SpecialKits sentinel values

// ❌ Wrong — crashes when kit is '__unspec__' or '__scanforkits__'
const compiler = kit.compilers?.['C'];

// ✅ Correct
if (kit.name !== SpecialKits.Unspecified && kit.name !== SpecialKits.ScanForKits) {
    const compiler = kit.compilers?.['C'];
}

5. Forgetting the driver instance guard

In kits mode, no driver is created without a kit:

// src/cmakeProject.ts
if (!this.useCMakePresets && !this.activeKit) {
    log.debug(localize('not.starting.no.kits', 'Not starting CMake driver: no kit selected'));
    return null;
}

Always handle null driver returns in calling code.


Testing checklist

  • [ ] Verified in presets mode (create a CMakePresets.json with configure + build presets)
  • [ ] Verified in kits/variants mode (remove preset files or set cmake.useCMakePresets: "never")
  • [ ] Verified with a single-config generator (Ninja or Unix Makefiles)
  • [ ] Verified with a multi-config generator (Visual Studio, Ninja Multi-Config, or Xcode)
  • [ ] SpecialKits sentinel values handled (no crash on __unspec__ kit)
  • [ ] null driver / null preset / null kit cases handled gracefully
  • [ ] Windows, macOS, and Linux path differences considered

See also: .github/copilot-instructions.md for project-wide conventions.

04 同仓库更多 Skills

microsoft
microsoft/vscode-cmake-tools

validation-project

Creates a validation project for testing a specific vscode-cmake-tools pull request. Use this skill when asked to create a validation project, test a PR, validate a pull request, or set up a PR validation environment. The skill creates a structured project directory with documentation, metadata, and checklists for systematically validating PR changes.

测试与质量
★ 1.7k
microsoft
microsoft/vscode-cmake-tools

pr-readiness

Verify that a pull request into microsoft/vscode-cmake-tools meets contribution requirements. Use when preparing, reviewing, or finalizing a PR to check for a descriptive title, a meaningful description, a properly formatted CHANGELOG entry, code correctness, regression risks, adherence to existing patterns, and whether documentation updates are needed.

★ 1.7k
microsoft
microsoft/vscode-cmake-tools

backend-tests

Use when writing unit tests under test/unit-tests/backend/*.test.ts that run in Node with Mocha+Chai and no VS Code API. For pure logic: parsers, helpers, env merging. Triggers: "backend test", "unit test", "mocha test without vscode".

开发工程师内容创作者测试与质量后端与接口
★ 1.7k
microsoft
microsoft/vscode-cmake-tools

add-setting

Use when adding a new cmake.* configuration setting. Touches package.json (contributes.configuration), package.nls.json, src/config.ts (interface + getter), docs/cmake-settings.md, and CHANGELOG.md. Triggers: "add setting", "new setting", "add configuration".

★ 1.7k
microsoft
microsoft/vscode-cmake-tools

add-diagnostic-parser

Use when adding a compiler or tool output parser for the Problems panel. Touches src/diagnostics/<name>.ts, src/diagnostics/build.ts, package.json (cmake.enabledOutputParsers), and package.nls.json. Triggers: "add parser", "new diagnostic parser", "parse compiler output".

★ 1.7k
microsoft
microsoft/vscode-cmake-tools

add-command

Use when adding a new cmake.* command to CMake Tools. Touches package.json (contributes.commands), package.nls.json, src/extension.ts (funs array), and CHANGELOG.md. Triggers: "add command", "register command", "new command palette entry".

★ 1.7k