Adding a New Configuration Setting

Recipe for adding a new cmake.* setting to CMake Tools.

Files you must touch

Step 1 — Declare the setting in package.json

Add an entry inside contributes.configuration.properties. Key format is cmake.<settingName>.

// package.json  →  contributes.configuration.properties
"cmake.myNewSetting": {
  "type": "boolean",
  "default": false,
  "description": "%cmake-tools.configuration.cmake.myNewSetting.description%",
  "scope": "resource"
}

Rules

• type — "boolean", "string", "number", "array", "object", or use "oneOf" for union types.
• default — always required.
• scope — use "resource" for project-specific settings (most common), "window" for global UI settings, "machine-overridable" for tool paths.
• description or markdownDescription — must use an NLS key, never a bare string.
• NLS key format: %cmake-tools.configuration.cmake.<settingName>.description% (wrapped in %).

Real example — cmake.saveBeforeBuild

"cmake.saveBeforeBuild": {
  "type": "boolean",
  "default": true,
  "description": "%cmake-tools.configuration.cmake.saveBeforeBuild.description%",
  "scope": "resource"
}

Step 2 — Add the English string to package.nls.json

Add the NLS key (without the % wrappers) and its English text:

"cmake-tools.configuration.cmake.myNewSetting.description": "Description of what this setting does."

Do not modify any file under i18n/. Translations are handled separately.

Step 3 — Wire up src/config.ts (three changes)

3a — Add property to ExtensionConfigurationSettings

// src/config.ts  →  ExtensionConfigurationSettings interface
export interface ExtensionConfigurationSettings {
    // ... existing properties ...
    myNewSetting: boolean;
}

The type must match what you declared in package.json.

3b — Add EventEmitter to the emitters map

// src/config.ts  →  ConfigurationReader.emitters
private readonly emitters: EmittersOf<ExtensionConfigurationSettings> = {
    // ... existing emitters ...
    myNewSetting: new vscode.EventEmitter<boolean>(),
};

The emitter type parameter must match the interface property type.

3c — Add a getter

Simple pass-through getter (most settings):

get myNewSetting(): boolean {
    return this.configData.myNewSetting;
}

Getter with transformation logic (e.g., sourceDirectory normalizes to array):

get sourceDirectory(): string[] {
    if (!Array.isArray(this.configData.sourceDirectory)) {
        return [this.configData.sourceDirectory];
    }
    return this.configData.sourceDirectory;
}

Step 4 — Document in docs/cmake-settings.md

Add a row to the settings table. Keep alphabetical order.

| `cmake.myNewSetting` | Description of what this setting does. | `false` | no |

Table columns:

Step 5 — Add a CHANGELOG entry

Add an entry under the current version in CHANGELOG.md, in the Features: or Improvements: section.

Verification checklist

• package.json — setting declared with correct type, default, scope, and NLS key
• package.nls.json — English string added
• src/config.ts — interface property, emitter, and getter all added
• docs/cmake-settings.md — table row added in alphabetical order
• CHANGELOG.md — entry added
• yarn compile succeeds (or npm run compile)
• No files under i18n/ were modified

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